Add basic usage documentation structure

ironcore-dev · Dec 16, 2024 · 7e3ad2f · 7e3ad2f
1 parent b575415
commit 7e3ad2f
Show file tree

Hide file tree

Showing 39 changed files with 92 additions and 66 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -2,5 +2,3 @@
 
 This page contains the documentation of the [ironcore](https://github.com/ironcore-dev/ironcore) project which is part 
 of the [ironcore-dev](https://github.com/ironcore-dev) organization.
-
---8<-- "hack/docs/abbreviations.md"
diff --git a/docs/api-reference/overview.md b/docs/api-reference/overview.md
@@ -3,12 +3,12 @@
 This is the home of the API reference documentation grouped by the various API groups. The content in each subgroup is
 automatically generated from the Go types in the `apis` folder. For more information on how the documentation is built
 and how it can be updated please refer to
-the [Updating API Reference Documentation](/development/documentation/#api-reference-documentation)
+the [Updating API Reference Documentation](../development/documentation.md#api-reference-documentation)
 in the documentation development guide.
 
-* [Core](../core)
-* [IPAM](../ipam)
-* [Compute](../compute)
-* [Networking](../networking)
-* [Storage](../storage)
-* [Common](../common)
+* [Core](core.md)
+* [IPAM](ipam.md)
+* [Compute](compute.md)
+* [Networking](networking.md)
+* [Storage](storage.md)
+* [Common](common.md)
diff --git a/docs/concepts/iri.md → docs/architecture/iri.md b/docs/concepts/iri.md → docs/architecture/iri.md
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -0,0 +1 @@
+# IronCore Architecture
diff --git a/docs/development/contribution.md b/docs/development/contribution.md
@@ -112,5 +112,3 @@ We use GitHub issues to track bugs and enhancement requests. Please provide as m
 Therefore, contributors may use but aren't restricted to the issue template provided by the IronCore maintainers.
 
 Issues and pull requests are tracked in the [backlog](https://github.com/ironcore-dev/ironcore/projects/1) for this project.
-
---8<-- "hack/docs/abbreviations.md"
diff --git a/docs/development/documentation.md b/docs/development/documentation.md
@@ -5,7 +5,7 @@ All documentation related content can be found in the `/docs` folder. New conten
 [MkDocs](https://www.mkdocs.org/) and [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) are then used to render the contents of the `/docs` folder to have a more user-friendly experience when browsing the projects' documentation.
 
 !!! note
-    One exception to the [common contribution process](/development/contribution/#steps-to-contribute) builds the `docs/api-reference` folder. The folder contains auto-generated CRD reference documentation of the project, no manual contributions should be applied as they will be overwritten in the next generation step.
+    One exception to the [common contribution process](contribution.md#steps-to-contribute) builds the `docs/api-reference` folder. The folder contains auto-generated CRD reference documentation of the project, no manual contributions should be applied as they will be overwritten in the next generation step.
     To read more: [Updating API Reference Documentation](#api-reference-documentation)  section.
 
 ## Requirements:
@@ -41,13 +41,9 @@ make clean-docs
 
 ## Writing Content
 
-### Abbreviations
-Abbreviations are defined centrally in the following file `/hack/docs/abbreviations.md`. In case you introduce any new abbreviation to your content, please make sure to add a corresponding entry there.
-Please include the statement `--8<-- "hack/docs/abbreviations.md"` at the end of each Markdown file. This will ensure that the abbreviation highlighting will work correctly.
-
 ## API Reference Documentation
 
-The [API reference documentation](/api-reference/overview/) contains auto-generated description from the CRD definition of the [ironcore](https://github.com/ironcore-dev/ironcore) project.
+The [API reference documentation](../api-reference/overview.md) contains auto-generated description from the CRD definition of the [ironcore](https://github.com/ironcore-dev/ironcore) project.
 We are using the [gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs) project to generate the content. Under the hood we are using `go generate` instructions defined in each version type `doc.go`.
 The needed instructions to generate documentation for the `core/v1alpha1` types are in the example below:
 
@@ -63,5 +59,3 @@ make docs
 
 !!! note
     The generated output should be part of your pull request.
-
---8<-- "hack/docs/abbreviations.md"
diff --git a/docs/development/setup.md b/docs/development/setup.md
@@ -101,5 +101,3 @@ To remove the APIs from your cluster, simply run
 ```shell
 make uninstall
 ```
-
---8<-- "hack/docs/abbreviations.md"
diff --git a/docs/development/testing.md b/docs/development/testing.md
@@ -197,5 +197,3 @@ KUBEBUILDER_ASSETS=/PATH_TO_MY_WORKSPACE/ironcore-dev/ironcore/testbin/bin
 ```
 
 This is typically the location of the Kubernetes control plane binaries on your machine.
-
---8<-- "hack/docs/abbreviations.md"
diff --git a/docs/proposals/00-template.md b/docs/proposals/00-template.md
@@ -1,7 +1,7 @@
 ---
-title: OEP Title
+title: IEP Title
 
-oep-number: NNNN
+iep-number: NNNN
 
 creation-date: 20XX-XX-XX
 
@@ -19,7 +19,7 @@ reviewers:
 
 ---
 
-# OEP-NNNN: Your short, descriptive title
+# IEP-NNNN: Your short, descriptive title
 
 ## Table of Contents
 

diff --git a/docs/proposals/01-networking-integration.md b/docs/proposals/01-networking-integration.md
@@ -1,7 +1,7 @@
 ---
 title: Networking Integration
 
-oep-number: 1
+iep-number: 1
 
 creation-date: 2022-17-03
 
@@ -22,7 +22,7 @@ reviewers:
 
 ---
 
-# OEP-1: Networking Integration
+# IEP-1: Networking Integration
 
 ## Table of Contents
 
@@ -39,7 +39,7 @@ Networking is a crucial part in a modern cloud system: It enables systems to com
 outside world. Orchestrating traffic, auditing it and gaining visibility of what is the desired state is key to a modern
 network architecture.
 
-Key of this OEP is to define the user-facing network API as well as its implications on any other type and the overall
+Key of this IEP is to define the user-facing network API as well as its implications on any other type and the overall
 structure of `ironcore`.
 
 ## Motivation

diff --git a/docs/proposals/02-machine-console-access.md b/docs/proposals/02-machine-console-access.md
@@ -1,7 +1,7 @@
 ---
 title: Machine Console Access
 
-oep-number: 2
+iep-number: 2
 
 creation-date: 2022-12-05
 
@@ -19,7 +19,7 @@ reviewers:
 
 ---
 
-# OEP-02: Machine Console Access
+# IEP-02: Machine Console Access
 
 ## Table of Contents
 

diff --git a/docs/proposals/03-loadbalancer.md b/docs/proposals/03-loadbalancer.md
@@ -1,7 +1,7 @@
 ---
 title: Network Loadbalancer
 
-oep-number: 3
+iep-number: 3
 
 creation-date: 2022-10-18
 
@@ -21,7 +21,7 @@ reviewers:
 
 ---
 
-# OEP-3: Network Loadbalancer
+# IEP-3: Network Loadbalancer
 
 ## Table of Contents
 
@@ -43,7 +43,7 @@ load balancers, since they can be used as a foundation for the higher level load
 
 ## Motivation
 
-A `VirtualIP` ([OEP-1](01-networking-integration.md#the-virtualip-type)) allows to expose a `NetworkInterface`
+A `VirtualIP` ([IEP-1](01-networking-integration.md#the-virtualip-type)) allows to expose a `NetworkInterface`
 with a stable public IP. Services running on a `Machine` using that `NetworkInterface` can be consumed this way.
 However, if the `Machine` or the service running on that `Machine` crashes, the service will have an outage.
 To be more resilient and to scale beyond single `NetworkInterface`s, a `LoadBalancer` allows targeting multiple
@@ -55,7 +55,7 @@ To be more resilient and to scale beyond single `NetworkInterface`s, a `LoadBala
 - Load balancers should allow specifying their IP stack (`IPv4` / `IPv6` / dual stack). Public IP addresses
   should be allocated according to the specified IP stack.
 - Load balancers should support multiple target `NetworkInterface`s (
-  see ([OEP-1](01-networking-integration.md#the-networkinterface-type))
+  see ([IEP-1](01-networking-integration.md#the-networkinterface-type))
 - The load balancer should dynamically watch for target `NetworkInterface`s.
 - All target `NetworkInterface`s must be in the same `Network`.
 - The load balancer should be able to filter unwanted traffic. The filtering must not alter the packages.
@@ -87,7 +87,7 @@ its `status.ips`.
 `ports` defines an allow list of which traffic should be handled by a `LoadBalancer`. A `port` consists of
 a `protocol`, `port` and an optional `portEnd` to support port range filtering.
 `networkRef` defines the target `Network` a `NetworkInterface` has to be in in order to be an eligible target
-for traffic forwarding (see [OEP-1](01-networking-integration.md#the-networkinterface-type)).
+for traffic forwarding (see [IEP-1](01-networking-integration.md#the-networkinterface-type)).
 
 [//]: # (@formatter:off)
 ```yaml

diff --git a/docs/proposals/04-nat-gateway.md b/docs/proposals/04-nat-gateway.md
@@ -1,7 +1,7 @@
 ---
 title: NAT Gateway
 
-oep-number: 4
+iep-number: 4
 
 creation-date: 2022-18-10
 
@@ -21,7 +21,7 @@ reviewers:
 
 ---
 
-# OEP-4: Cloud Nate Gateway
+# IEP-4: Cloud Nate Gateway
 
 ## Table of Contents
 

diff --git a/docs/proposals/05-object-storage.md b/docs/proposals/05-object-storage.md
@@ -1,7 +1,7 @@
 ---
 title: Object Storage
 
-oep-number: 5
+iep-number: 5
 
 creation-date: 2022-12-19
 
@@ -19,7 +19,7 @@ reviewers:
 
 ---
 
-# OEP-5: Object Storage
+# IEP-5: Object Storage
 
 ## Table of Contents
 

diff --git a/docs/proposals/06-storage-encryption.md b/docs/proposals/06-storage-encryption.md
@@ -1,7 +1,7 @@
 ---
 title: Storage Encryption
 
-oep-number: 6
+iep-number: 6
 
 creation-date: 2023-01-03
 
@@ -20,7 +20,7 @@ reviewers:
 
 ---
 
-# OEP-6: Storage Encryption
+# IEP-6: Storage Encryption
 
 ## Table of Contents
 

diff --git a/docs/proposals/07-quota.md b/docs/proposals/07-quota.md
@@ -1,7 +1,7 @@
 ---
 title: Quota
 
-oep-number: 7
+iep-number: 7
 
 creation-date: 2023-01-19
 
@@ -19,7 +19,7 @@ reviewers:
 
 ---
 
-# OEP-7: Quota
+# IEP-7: Quota
 
 ## Table of Contents
 

diff --git a/docs/proposals/08-internal-load-balancer.md b/docs/proposals/08-internal-load-balancer.md
@@ -1,7 +1,7 @@
 ---
-title: OEP Title
+title: IEP Title
 
-oep-number: 8
+iep-number: 8
 
 creation-date: 2023-03-16
 
@@ -14,7 +14,7 @@ authors:
 
 ---
 
-# OEP-8: Internal Load Balancers
+# IEP-8: Internal Load Balancers
 
 ## Table of Contents
 

diff --git a/docs/proposals/09-network-peering.md b/docs/proposals/09-network-peering.md
@@ -1,7 +1,7 @@
 ---
 title: Network Peering
 
-oep-number: 9
+iep-number: 9
 
 creation-date: 2023-03-17
 
@@ -18,7 +18,7 @@ reviewers:
 
 ---
 
-# OEP-9: Network Peering
+# IEP-9: Network Peering
 
 ## Table of Contents
 
@@ -35,7 +35,7 @@ Network peering is a technique used to interleave two isolated networks, allowin
 members of both networks to communicate with each other as if they were in the same
 networking domain. This proposal describes how to introduce network peering to
 `ironcore`, building upon the existing concepts that were proposed in the
-[Networking Integration OEP](01-networking-integration.md).
+[Networking Integration IEP](01-networking-integration.md).
 
 ## Motivation
 

diff --git a/docs/proposals/10-network-policies.md b/docs/proposals/10-network-policies.md
@@ -1,7 +1,7 @@
 ---
 title: Network Policies
 
-oep-number: 10
+iep-number: 10
 
 creation-date: 2023-04-13
 
@@ -18,7 +18,7 @@ reviewers:
 
 ---
 
-# OEP-10: Network Policies
+# IEP-10: Network Policies
 
 ## Table of Contents
 
@@ -38,7 +38,7 @@ communicate with the public internet (if connected). This imposes a big security
 risk which has to be properly addressed in each modern infrastructure.
 This proposal describes how to introduce network policies as a means to regulate
 traffic inside a network building upon the existing concepts that were proposed in the
-[Networking Integration OEP](01-networking-integration.md).
+[Networking Integration IEP](01-networking-integration.md).
 
 ## Motivation
 

diff --git a/docs/usage/compute/machine.md b/docs/usage/compute/machine.md
@@ -0,0 +1 @@
+# Machine
diff --git a/docs/usage/compute/machineclass.md b/docs/usage/compute/machineclass.md
@@ -0,0 +1 @@
+# MachineClass
diff --git a/docs/usage/compute/machinepool.md b/docs/usage/compute/machinepool.md
@@ -0,0 +1 @@
+# MachinePool
diff --git a/docs/usage/core/resourcequota.md b/docs/usage/core/resourcequota.md
@@ -0,0 +1 @@
+# ResourceQuota
diff --git a/docs/usage/installation.md b/docs/usage/installation.md
@@ -0,0 +1 @@
+# Installing IronCore
diff --git a/docs/usage/ipam/prefix.md b/docs/usage/ipam/prefix.md
@@ -0,0 +1 @@
+# Prefix
diff --git a/docs/usage/networking/loadbalancer.md b/docs/usage/networking/loadbalancer.md
@@ -0,0 +1 @@
+# LoadBalancer
diff --git a/docs/usage/networking/natgateway.md b/docs/usage/networking/natgateway.md
@@ -0,0 +1 @@
+# NATGateway
diff --git a/docs/usage/networking/network.md b/docs/usage/networking/network.md
@@ -0,0 +1 @@
+# Network
diff --git a/docs/usage/networking/networkinterface.md b/docs/usage/networking/networkinterface.md
@@ -0,0 +1 @@
+# NetworkInterface
diff --git a/docs/usage/networking/networkpolicy.md b/docs/usage/networking/networkpolicy.md
@@ -0,0 +1 @@
+# NetworkPolicy
diff --git a/docs/usage/networking/virtualip.md b/docs/usage/networking/virtualip.md
@@ -0,0 +1 @@
+# VirtualIP
diff --git a/docs/usage/storage/bucket.md b/docs/usage/storage/bucket.md
@@ -0,0 +1 @@
+# Bucket
diff --git a/docs/usage/storage/bucketclass.md b/docs/usage/storage/bucketclass.md
@@ -0,0 +1 @@
+# BucketClass
diff --git a/docs/usage/storage/bucketpool.md b/docs/usage/storage/bucketpool.md
@@ -0,0 +1 @@
+# BucketPool
diff --git a/docs/usage/storage/volume.md b/docs/usage/storage/volume.md
@@ -0,0 +1 @@
+# Volume
diff --git a/docs/usage/storage/volumeclass.md b/docs/usage/storage/volumeclass.md
@@ -0,0 +1 @@
+# VolumeClass
diff --git a/docs/usage/storage/volumepool.md b/docs/usage/storage/volumepool.md
@@ -0,0 +1 @@
+# VolumePool
diff --git a/hack/docs/abbreviations.md b/hack/docs/abbreviations.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,5 +2,3 @@

		This page contains the documentation of the [ironcore](https://github.com/ironcore-dev/ironcore) project which is part
		of the [ironcore-dev](https://github.com/ironcore-dev) organization.

		--8<-- "hack/docs/abbreviations.md"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -112,5 +112,3 @@ We use GitHub issues to track bugs and enhancement requests. Please provide as m
		Therefore, contributors may use but aren't restricted to the issue template provided by the IronCore maintainers.

		Issues and pull requests are tracked in the [backlog](https://github.com/ironcore-dev/ironcore/projects/1) for this project.

		--8<-- "hack/docs/abbreviations.md"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -197,5 +197,3 @@ KUBEBUILDER_ASSETS=/PATH_TO_MY_WORKSPACE/ironcore-dev/ironcore/testbin/bin
		```

		This is typically the location of the Kubernetes control plane binaries on your machine.

		--8<-- "hack/docs/abbreviations.md"