Rewrote to 'diataxis by feature'

nais/system#63 Co-authored-by: Johnny Horvi <johnny@horvi.no>
nais · May 15, 2024 · 196d0a8 · 196d0a8
1 parent a0234c6
commit 196d0a8
Show file tree

Hide file tree

Showing 253 changed files with 2,889 additions and 2,354 deletions.
diff --git a/build.sh b/build.sh
@@ -1,4 +1,5 @@
 #! /bin/bash
+set -e
 
 rm -rf ./out ./docs-base
 mkdir -p ./out ./docs-base
@@ -10,6 +11,7 @@ for TENANT in $@;
   do
     rm -rf ./docs
     cp -r ./docs-base ./docs
-    cp -rf ./tenants/$TENANT/* ./docs
+    cp -rf ./tenants/$TENANT/* ./docs || true
     TENANT=$TENANT poetry run mkdocs build --strict -d out/$TENANT
   done
+
diff --git a/docs/.pages b/docs/.pages
@@ -0,0 +1,17 @@
+nav:
+  - "":
+    - explanations
+    - tutorials
+  - "":
+    - workloads
+    - build
+    - authentication
+    - observability
+    - persistence
+    - security
+    - Other services: services
+  - "":
+    - operate
+  - "":
+    - tags.md
+    - ...
diff --git a/docs/README.md b/docs/README.md
@@ -2,57 +2,46 @@
 hide:
   - feedback
   - footer
+  - toc
 ---
-
-<style> // hides the edit button on the start-page
-  .md-typeset h1,
+<!-- This hides the edit button on the start page -->
+<style>
   .md-content__button {
     display: none;
   }
 </style>
 
-# NAIS Documentation
+# :wave: **Welcome to the NAIS developer documentation!**
 
-<div class="grid cards" markdown>
--   :seedling: **Getting Started?**
+Here you'll find _explanations_[^1], _how-to guides_[^2], and _references_[^3] for all things NAIS.
 
-    ---
-    - Initially it's a good idea to learn about [what NAIS is](./explanation/nais.md) to get an idea of the fundamentals.
-    - Once you're familiar with the basic concepts, move on to the [Hello NAIS](./tutorial/hello-nais/hello-nais-1.md) tutorial to get your first app running.
+### :seedling: **New to NAIS?**
 
-</div>
+Start here to get an idea of the fundamentals.
 
 <div class="grid cards" markdown>
--   :rocket: **Tutorials**
-
-    ---
-
-    Learning-oriented lessons that take you through a series of steps to complete a project. Most useful when you want to get started with NAIS.
-
-    [:octicons-arrow-right-24: Tutorials](tutorial/README.md)
-
-- :dart: **How-to guides**
-
-    ---
 
-    Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done.
+- :ok_hand: [**What is NAIS?**](explanations/nais.md)
+- :student: [**Your first application; Hello NAIS**](tutorials/hello-nais.md)
 
-    [:octicons-arrow-right-24: How-to guides](how-to-guides/README.md)
-
-- :bulb: **Explanation**
-
-    ---
-
-    Big-picture explanations of higher-level concepts. Most useful when you want to understand how NAIS works.
-
-    [:octicons-arrow-right-24: Explanations](explanation/README.md)
+</div>
 
-- :books: **Reference**
+### :technologist: **Already familiar with NAIS?**
 
-    ---
+What can we help you with today?
 
-    Reference documentation for the NAIS platform. Most useful when you need to look up details about a specific feature.
+<div class="grid cards" markdown>
 
-    [:octicons-arrow-right-24: Reference](reference/README.md)
+- :package: [**Run your code**](workloads/README.md)
+- :rocket: [**Build and deploy your code**](build/README.md)
+- :open_file_folder: [**Store your data**](persistence/README.md)
+- :closed_lock_with_key: [**Authenticate your users**](security/auth/README.md)
+- :telescope: [**Gain insight into your workloads**](observability/README.md)
+- :wrench: [**Manage your workloads and services**](operate/README.md)
+- :heavy_plus_sign: [**Explore the rest of NAIS**](services/README.md)
 
 </div>
+
+[^1]: an :bulb: [_explanation_](tags.md#explanation) presents higher-level concepts. Most useful when you want to understand how NAIS works.
+[^2]: a :dart: [_how-to guide_](tags.md#how-to) helps you achieve a specific goal. Most useful when you're trying to get something done.
+[^3]: a :books: [_reference_](tags.md#reference) contains technical descriptions and specifications. Most useful when you need to look up details about a specific feature.
diff --git a/docs/authentication/.pages b/docs/authentication/.pages
@@ -0,0 +1 @@
+hide: true
diff --git a/docs/authentication/machines/README.md b/docs/authentication/machines/README.md
@@ -0,0 +1 @@
+# Machines
diff --git a/docs/authentication/users/README.md b/docs/authentication/users/README.md
@@ -0,0 +1 @@
+# Users
diff --git a/docs/build/.pages b/docs/build/.pages
@@ -0,0 +1,5 @@
+title: Build and deploy
+nav:
+- README.md
+- 🎯 How-To: how-to
+- ...
diff --git a/docs/build/README.md b/docs/build/README.md
@@ -0,0 +1,25 @@
+---
+tags: [build, deploy, explanation, services]
+---
+
+# Build and deploy
+
+To make your application available to others, you need to build and deploy it.
+
+NAIS attempts to make this as simple as possible by providing a set of composable [GitHub Actions](https://docs.github.com/en/actions).
+
+Use these actions to compose your own build and deploy pipeline through [Github Actions workflows](https://docs.github.com/en/actions/using-workflows). 
+
+## GitHub Actions
+
+:books: [nais/docker-build-push](https://github.com/nais/docker-build-push)
+
+:books: [nais/deploy](https://github.com/nais/deploy/tree/master/actions/deploy)
+
+See the respective GitHub Action links for detailed configuration options.
+
+## What's next
+
+:dart: [Build and deploy with Github Actions](how-to/build-and-deploy.md)
+
+:dart: [Set up auto-merge with Dependabot](how-to/dependabot-auto-merge.md)
diff --git a/docs/how-to-guides/github-action.md → docs/build/how-to/build-and-deploy.md b/docs/how-to-guides/github-action.md → docs/build/how-to/build-and-deploy.md
@@ -1,16 +1,20 @@
+---
+tags: [build, deploy, how-to]
+---
+
 # Build and deploy with Github Actions
 
 This how-to guide shows you how to build and deploy your application using [Github Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions) and the NAIS deploy action.
 
 ## Prerequisites
 
-- You're part of a [NAIS team](./team.md)
+- You're part of a [NAIS team](../../operate/how-to/create-team.md)
 - A Github repository where the NAIS team has access
-- The repository contains a valid [workload manifest](../explanation/workloads/README.md)
+- The repository contains a valid [workload manifest](../../workloads/README.md)
 
 ## Authorize your Github repository for deployment
 
-1. Open [NAIS console](https://console.<<tenant()>>.cloud.nais.io) in your browser and select your team.
+1. Open [NAIS Console](https://console.<<tenant()>>.cloud.nais.io) in your browser and select your team.
 2. Select the `Repositories` tab
 3. Find the repository you want to deploy from, and click `Authorize`
 
@@ -52,7 +56,7 @@ This how-to guide shows you how to build and deploy your application using [Gith
     ```
 
 This example workflow is a minimal example that builds, signs, and pushes your container image to the image registry.
-It then deploys the [app.yaml](../reference/application-spec.md), injecting the image tag from the previous step.
+It then deploys the [app.yaml](../../workloads/application/reference/application-spec.md), injecting the image tag from the previous step.
 
 When this file is pushed to the `main` branch, the workflow will be triggered and you are all set.
 

diff --git a/docs/how-to-guides/dependabot-auto-merge.md → docs/build/how-to/dependabot-auto-merge.md b/docs/how-to-guides/dependabot-auto-merge.md → docs/build/how-to/dependabot-auto-merge.md
@@ -1,3 +1,7 @@
+---
+tags: [build, deploy, how-to]
+---
+
 # Dependabot with auto-merge
 
 [working-with-dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot

diff --git a/docs/explanation/.pages b/docs/explanation/.pages
diff --git a/docs/explanation/README.md b/docs/explanation/README.md
diff --git a/docs/explanation/database/opensearch.md b/docs/explanation/database/opensearch.md
diff --git a/docs/explanation/naisdevice.md b/docs/explanation/naisdevice.md
diff --git a/docs/explanation/restoring.md b/docs/explanation/restoring.md
diff --git a/docs/explanation/team.md b/docs/explanation/team.md
diff --git a/docs/explanation/under-the-hood.md b/docs/explanation/under-the-hood.md
diff --git a/docs/explanation/workloads/README.md b/docs/explanation/workloads/README.md
diff --git a/docs/explanation/workloads/application.md b/docs/explanation/workloads/application.md
diff --git a/docs/explanation/workloads/job.md b/docs/explanation/workloads/job.md
diff --git a/docs/explanation/zero-trust.md b/docs/explanation/zero-trust.md
diff --git a/docs/explanations/.pages b/docs/explanations/.pages
@@ -0,0 +1,4 @@
+nav:
+- nais.md
+- team.md
+- under-the-hood.md
diff --git a/docs/explanation/nais.md → docs/explanations/nais.md b/docs/explanation/nais.md → docs/explanations/nais.md
@@ -1,3 +1,7 @@
+---
+tags: [explanation, nais]
+---
+
 # What is NAIS?
 
 NAIS is a platform aiming to provide you with the technical capabilities you need to develop and run software in a safe and enjoyable way.
@@ -8,7 +12,7 @@ In order to support this idea, we aim to provide you with functionality that jus
 
 You can think of the provided functionality as building blocks, where you as a developer can select the ones that fit your specific needs.
 
-The fundamental building block provided by NAIS is a robust and secure runtime environment for your [workloads](./workloads/README.md).
+The fundamental building block provided by NAIS is a robust and secure runtime environment for your [workloads](../workloads/README.md).
 
 When your workload is up and running, it’s crucial to be able to observe how it’s doing. Here the platform provides you with the tooling you need to log, emit metrics and run traces.