Rewrote to 'diataxis by feature'

nais/system#63 Co-authored-by: Trong Huu Nguyen <trong.huu.nguyen@nav.no>
nais · May 14, 2024 · 65d31e3 · 65d31e3
1 parent 7fd5457
commit 65d31e3
Show file tree

Hide file tree

Showing 243 changed files with 2,681 additions and 1,634 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -1,10 +1,5 @@
 name: Build and publish doc
-
-on:
-  push:
-    branches: 
-      - main
-
+on: push
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -42,6 +37,7 @@ jobs:
           ./build.sh nav ssb ci-nais dev-nais tenant
 
   publish:
+    if: github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest
     strategy:

diff --git a/build.sh b/build.sh
@@ -6,11 +6,11 @@ mkdir -p ./out ./docs-base
 # Copy documentation to base folder as we need to use docs as a staging folder
 cp -r ./docs/* ./docs-base
 
-for TENANT in $@; 
+for TENANT in $@;
   do 
     rm -rf ./docs
     cp -r ./docs-base ./docs
     cp -rf ./tenants/$TENANT/* ./docs
-    TENANT=$TENANT poetry run mkdocs build --no-strict -d out/$TENANT
+    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>
 
-- :computer: **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,23 @@
+---
+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,12 +1,16 @@
+---
+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
 
@@ -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