Skip to content

Commit

Permalink
Docs Full IA Update (#1639)
Browse files Browse the repository at this point in the history
Based on user feedback and to improve the information architecture, we
are creating a "Getting Started" folder. All links associated with the
changed files have been modified accordingly.

-  Remove operator manual
-  Create "Getting Started" file
- Move Understand the Basics, Core Concepts, and Getting Started into
one folder
-  Fix any broken links that to pointed set up and install


## Related Issue

Fixes #1628 
Relates to #1397 

[PUBLIC - Zarf Project - New Docs Information
Architecture.pdf](https://github.com/defenseunicorns/zarf/files/11297954/PUBLIC.-.Zarf.Project.-.New.Docs.Information.Architecture.pdf)

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [X] Other (security config, docs update, etc)

## Checklist before merging

- [X] Test, docs, adr added or updated as needed
- [X] [Contributor Guide
Steps](https://github.com/defenseunicorns/zarf/blob/main/CONTRIBUTING.md#developer-workflow)
followed

---------

Co-authored-by: Wayne Starr <[email protected]>
Co-authored-by: Wayne Starr <[email protected]>
Co-authored-by: razzle <[email protected]>
  • Loading branch information
4 people committed May 2, 2023
1 parent ce78441 commit 8653011
Show file tree
Hide file tree
Showing 188 changed files with 644 additions and 858 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@
*What are we hoping to validate?*



## Testing Plan ##
User persona:
Sample Group:
Expand All @@ -12,6 +11,6 @@ Sample Group:
## Additional context ##
*Screenshot or link to what needs to be tested*

Related to issue
Related to issue

## Link to Test & Results ##
2 changes: 1 addition & 1 deletion .github/workflows/scan-labels.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@ jobs:
steps:
- uses: yogevbd/[email protected]
with:
BANNED_LABELS: "needs-docs,needs-tests,needs-adr,needs-git-sign-off,needs-walkthrough"
BANNED_LABELS: "needs-docs,needs-tests,needs-adr,needs-git-sign-off,needs-tutorial"
2 changes: 1 addition & 1 deletion .markdownlintignore
Original file line number Diff line number Diff line change
@@ -1 +1 @@
docs/4-user-guide/1-the-zarf-cli/100-cli-commands/
docs/2-the-zarf-cli/100-cli-commands/
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Our E2E tests can be found in the `/test` folder and follow the journey of someo
Our Unit tests can be found as `*_test.go` files inside the package that they are designed to test. These are also run in CI and are designed to test small functions with clear interfaces that would be difficult to test otherwise. As a general rule, we are limiting unit tests to the `src/pkg/*` folder.

All of our tests should be able to be run locally or in CI.
You can learn more about the testing of Zarf [here](docs/6-contribute-to-zarf/2-testing.md).
You can learn more about the testing of Zarf [here](docs/12-contribute-to-zarf/2-testing.md).

## Documentation

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ _<https://www.youtube.com/watch?v=WnOYlFVVKDE>_

To try Zarf out for yourself, visit the ["Try It Now"](https://zarf.dev/install) section on our website, and if you want to learn more about Zarf and its use cases visit [docs.zarf.dev](https://docs.zarf.dev/docs/zarf-overview).

From the docs you can learn more about [installation](https://docs.zarf.dev/docs/operator-manual/set-up-and-install), [using the CLI](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/), [making packages](https://docs.zarf.dev/docs/user-guide/zarf-packages/), and the [Zarf package schema](https://docs.zarf.dev/docs/user-guide/zarf-schema).
From the docs you can learn more about [installation](https://docs.zarf.dev/docs/getting-started/#installing-zarf), [using the CLI](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/), [making packages](https://docs.zarf.dev/docs/user-guide/zarf-packages/), and the [Zarf package schema](https://docs.zarf.dev/docs/user-guide/zarf-schema).

Using Zarf in Github workflows? Check out the [setup-zarf](https://github.com/defenseunicorns/setup-zarf) action. Install any version of Zarf and its `init` package with zero added dependencies.

Expand Down
4 changes: 2 additions & 2 deletions adr/0011-scripts-actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ The `scripts` section of the `zarf.yaml` will be replaced with a new `actions` s
- `onDeploy` - Runs during `zarf package deploy`
- `onRemove` - Runs during `zarf package remove`

In addition to adding more lifecycle events, the `actions` section will also allow for more complex actions to be defined. New configurations include, setting the cmd directory, defining custom env variables, setting the number of retries, setting the max total seconds, muting the output, and [setting a variable](../docs/4-user-guide/5-component-actions.md#creating-dynamic-variables-from-actions) to be used in other actions or components.
In addition to adding more lifecycle events, the `actions` section will also allow for more complex actions to be defined. New configurations include, setting the cmd directory, defining custom env variables, setting the number of retries, setting the max total seconds, muting the output, and [setting a variable](../docs/3-create-a-zarf-package/7-component-actions.md#creating-dynamic-variables-from-actions) to be used in other actions or components.

Further details can be found in the `component-actions` [component actions documentation](../docs/4-user-guide/7-github-action.md), [component lifecycle documentation](../docs/4-user-guide/4-package-command-lifecycle.md), and the [example package](../examples/component-actions/README.md).
Further details can be found in the `component-actions` [component actions documentation](../docs/3-create-a-zarf-package/7-component-actions.md), [package create lifecycle documentation](../docs/3-create-a-zarf-package/6-package-create-lifecycle.md), [package deploy lifecycle documentation](../docs/4-deploy-a-zarf-package/2-package-deploy-lifecycle.md), and the [example package](../examples/component-actions/README.md).

## Consequences

Expand Down
2 changes: 1 addition & 1 deletion adr/0014-oci-publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ zarf-package-adr-arm64.tar.zst

With this new structure in place, we can now publish Zarf packages as OCI artifacts. Under the hood this implements the `oras` Go library using Docker's authentication system. For interacting with these packages, the `oci://` package path prefix has been added (ex. `zarf package publish oci://...`).

For an example of this in action, please see the [walkthrough](./docs/../../docs/13-walkthroughs/7-publish-and-deploy.md).
For an example of this in action, please see the corresponding [tutorial](../docs/6-zarf-tutorials/7-publish-and-deploy.md).

## Consequences

Expand Down
17 changes: 17 additions & 0 deletions docs-website/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,23 @@ const config = {
...args
}) {
const sidebarItems = await defaultSidebarItemsGenerator(args)
if (args.item.dirName === 'docs') {
// This hack places the examples tree at the 7th position in the sidebar
sidebarItems.splice(7, 0, {
type: 'category',
label: 'Package Examples',
link: {
type: 'doc',
id: 'examples/README',
},
items: [
{
type: 'autogenerated',
dirName: 'examples',
},
],
})
}
if (args.item.dirName === 'examples') {
// This hack removes the "Overview" page from the sidebar on the examples page
return sidebarItems.slice(1)
Expand Down
14 changes: 0 additions & 14 deletions docs-website/src/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,6 @@
const sidebars = {
docsSidebar: [
{ type: 'autogenerated', dirName: 'docs' },
{
type: 'category',
label: 'Package Examples',
link: {
type: 'doc',
id: 'examples/README',
},
items: [
{
type: 'autogenerated',
dirName: 'examples',
},
],
},
],
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@

<b style="color:#55ffff;"></b><b style="color:#55ffff;"> Application</b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Username </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Password </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Connect </b>
Registry <b style="color:#555555;"></b><b style="color:#555555;"> | </b>zarf-push <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Tka7dWq4GEit5G3GDX2dQwdh<b style="color:#555555;"></b><b style="color:#555555;"> | </b>zarf connect registry
Logging <b style="color:#555555;"></b><b style="color:#555555;"> | </b>zarf-admin<b style="color:#555555;"></b><b style="color:#555555;"> | </b>ysC9TEWsSm37pBmA3hvqrLN3<b style="color:#555555;"></b><b style="color:#555555;"> | </b>zarf connect logging
Logging <b style="color:#555555;"></b><b style="color:#555555;"> | </b>zarf-admin<b style="color:#555555;"></b><b style="color:#555555;"> | </b>ysC9TEWsSm37pBmA3hvqrLN3<b style="color:#555555;"></b><b style="color:#555555;"> | </b>zarf connect logging
</pre>
</body>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@
<b style="color:#ff55ff;"> </b><b style="color:#55ffff;">value</b>:<b style="color:#ff55ff;"> 2.8.1</b>
<b class=YEL>This package has 9 artifacts with software bill-of-materials (SBOM) included. You can view them now</b>
<b class=YEL>in the zarf-sbom folder in this directory or to go directly to one, open this in your browser:</b>
<b class=YEL>/Users/jason/src/github.com/jasonvanbrackel/zarf/docs/.examples/walkthroughs/zarf-sbom/sbom-viewer-docker.io_grafana_promtail_2.7.0.html</b>
<b class=YEL>/Users/jason/src/github.com/jasonvanbrackel/zarf/docs/.examples/tutorials/zarf-sbom/sbom-viewer-docker.io_grafana_promtail_2.7.0.html</b>
<b class=YEL></b>
<b class=YEL>* This directory will be removed after package deployment.</b>
<b class=YEL></b>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
<b class=YEL>Saving log file to</b>
<b class=YEL>/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-22-13-13-47-3918845089.log</b>
<b class=YEL></b><b style="color:#55ffff;"></b><b style="color:#55ffff;"> Package </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Components </b>
dos-games<b style="color:#555555;"></b><b style="color:#555555;"> | </b>[baseline]
dos-games<b style="color:#555555;"></b><b style="color:#555555;"> | </b>[baseline]
init <b style="color:#555555;"></b><b style="color:#555555;"> | </b>[zarf-injector zarf-seed-registry zarf-registry zarf-agent logging]
</pre>
</body>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@
<b style="color:#55ffff;"></b><b style="color:#55ffff;">Downloading k3s-airgap-images-arm64.tar.zst</b>
<b style="color:#55ff55;"></b><b style="color:#55ff55;"></b> <b style="color:#55ff55;"></b><b style="color:#55ff55;">Downloading https://github.com/k3s-io/k3s/releases/download/v1.24.1+k3s1/k3s-airgap-images-arm64.tar.zst</b>

<div style="background-color: #555555;">
<div style="background-color: #555555;">
<b style="background-color:#555555"></b><b style="background-color:#555555"> </b>
<b style="background-color:#555555"></b><b style="background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"> 📦 ZARF-INJECTOR COMPONENT </b><b style="background-color:#555555"></b><b style="background-color:#555555"></b>
<b style="background-color:#555555"></b><b style="background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"> </b><b style="background-color:#555555"></b><b style="background-color:#555555"></b>
Expand Down Expand Up @@ -96,7 +96,7 @@
<b style="background-color:#555555"></b><b style="background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"> 📦 ZARF-AGENT COMPONENT </b><b style="background-color:#555555"></b><b style="background-color:#555555"></b>
<b style="background-color:#555555"></b><b style="background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"> </b><b style="background-color:#555555"></b><b style="background-color:#555555"></b>
<b style="background-color:#555555"></b><b style="background-color:#555555"> </b>
</div>
</div>

<b style="color:#55ffff;"></b><b style="color:#55ffff;">Running "make init-package-local-agent AGENT_IMAGE="agent:local""</b>
docker buildx build --platform linux/amd64 --tag ghcr.io/defenseunicorns/zarf/agent:local .
Expand Down Expand Up @@ -138,7 +138,7 @@
<b style="background-color:#555555"></b><b style="background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"> 📦 LOGGING COMPONENT </b><b style="background-color:#555555"></b><b style="background-color:#555555"></b>
<b style="background-color:#555555"></b><b style="background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"> </b><b style="background-color:#555555"></b><b style="background-color:#555555"></b>
<b style="background-color:#555555"></b><b style="background-color:#555555"> </b>
</div>
</div>

<b style="color:#55ffff;"></b><b style="color:#55ffff;">Processing helm chart loki-stack:2.9.9 from repo https://grafana.github.io/helm-charts</b>
<b style="color:#55ffff;"></b><b style="color:#55ffff;">Loading 1 K8s manifests</b>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,10 +51,10 @@
<b class=YEL>/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-23-10-41-26-1175297225.log</b>
<b class=YEL></b><b style="color:#55ffff;"></b><b style="color:#55ffff;"> Connect Command </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Description </b>
zarf connect registry<b style="color:#555555;"></b><b style="color:#555555;"> | </b>Internal Zarf Registry (run zarf tools registry login to authenticate)
zarf connect doom <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play doom!!!
zarf connect games <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play some old dos games 🦄
zarf connect doom <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play doom!!!
zarf connect games <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play some old dos games 🦄

<b class=WHI>$ zarf connect games</b>
<b class=WHI>$ zarf connect games</b>
</pre>
</body>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,11 @@
</head>
<body>
<pre>
<b class=WHI>$ zarf package deploy ./zarf-package-dos-games-arm64.tar.zst</b>
<b class=WHI>$ zarf package deploy sget://defenseunicorns/zarf-hello-world:$(uname -m)</b>
<b class=YEL>Saving log file to</b>
<b class=YEL>/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-23-10-20-59-1265818177.log</b>
<b class=YEL></b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Loading Zarf Package ../examples/dos-games/zarf-package-dos-games-arm64.tar.zst</b>
<b style="color:#55ffff;"></b><b style="color:#55ffff;">Loading Zarf Package ../examples/dos-games/zarf-package-dos-games-arm64.tar.zst</b>
<b class=YEL></b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Loading Zarf Package sget://defenseunicorns/zarf-hello-world:$(uname -m)</b>
<b style="color:#55ffff;"></b><b style="color:#55ffff;">Loading Zarf Package sget://defenseunicorns/zarf-hello-world:$(uname -m)</b>

<b style="color:#55ffff;">kind</b>:<b style="color:#ff55ff;"> ZarfPackageConfig</b>
<b style="color:#ff55ff;"></b><b style="color:#55ffff;">metadata</b>:<b style="color:#55ffff;"></b>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@
<b style="color:#55ff55;"></b><b style="color:#55ff55;"></b> <b style="color:#55ff55;"></b><b style="color:#55ff55;">Zarf deployment complete</b>

<b style="color:#55ffff;"></b><b style="color:#55ffff;"> Connect Command </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Description </b>
zarf connect doom <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play doom!!!
zarf connect doom <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play doom!!!
zarf connect games<b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play some old dos games 🦄
</pre>
</body>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@
<b style="color:#55ff55;"></b><b style="color:#55ff55;"></b> <b style="color:#55ff55;"></b><b style="color:#55ff55;">Zarf deployment complete</b>

<b style="color:#55ffff;"></b><b style="color:#55ffff;"> Connect Command </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Description </b>
zarf connect doom <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play doom!!!
zarf connect doom <b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play doom!!!
zarf connect games<b style="color:#555555;"></b><b style="color:#555555;"> | </b>Play some old dos games 🦄
</pre>
</body>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@
<b style="background-color:#555555"></b><b style="background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"></b><b style="color:#ffffff;background-color:#555555"> </b><b style="background-color:#555555"></b><b style="background-color:#555555"></b>
<b style="background-color:#555555"></b><b style="background-color:#555555"> </b>
</div>

<b style="color:#55ffff;"></b><b style="color:#55ffff;">Loading the Zarf State from the Kubernetes cluster</b>
<b style="color:#55ffff;"></b><b style="color:#55ffff;">Loading the Zarf State from the Kubernetes cluster</b>
<b style="color:#55ffff;"></b><b style="color:#55ffff;">Opening tunnel 61264 -&gt; 5000 for svc/zarf-docker-registry in namespace zarf</b>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
<b class=YEL>/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-23-10-05-29-1632940529.log</b>
<b class=YEL></b><b style="color:#55ffff;"></b><b style="color:#55ffff;"> Package </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Components </b>
init <b style="color:#555555;"></b><b style="color:#555555;"> | </b>[zarf-injector zarf-seed-registry zarf-registry zarf-agent]
helm-oci-chart<b style="color:#555555;"></b><b style="color:#555555;"> | </b>[helm-oci-chart]
helm-oci-chart<b style="color:#555555;"></b><b style="color:#555555;"> | </b>[helm-oci-chart]
</pre>
</body>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -54,4 +54,4 @@
<b class=CYN>> zarf-package-helm-oci-chart-arm64-0.0.1.tar.zst</b>
</pre>
</body>
</html>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
<b class=YEL>/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-03-23-10-05-29-1632940529.log</b>
<b class=YEL></b><b style="color:#55ffff;"></b><b style="color:#55ffff;"> Package </b><b style="color:#555555;"></b><b style="color:#555555;"> | </b><b style="color:#55ffff;"></b><b style="color:#55ffff;">Components </b>
init <b style="color:#555555;"></b><b style="color:#555555;"> | </b>[zarf-injector zarf-seed-registry zarf-registry zarf-agent]
dos-games<b style="color:#555555;"></b><b style="color:#555555;"> | </b>[baseline]
dos-games<b style="color:#555555;"></b><b style="color:#555555;"> | </b>[baseline]
</pre>
</body>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -53,4 +53,4 @@
<b class="BOLD" style="color:#55ff55;">? </b><b class="BOLD">Choose or type the package file </b><b class=CYN>[</b><b class=CYN>tab for suggestions]</b>
</pre>
</body>
</html>
</html>
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,4 @@
<b class=CYN>> zarf-package-dos-games-amd64.tar.zst</b>
</pre>
</body>
</html>
</html>
Loading

0 comments on commit 8653011

Please sign in to comment.