mkdocs.yml

acrlabs · Nov 15, 2023 · ee7336c · ee7336c
1 parent 124c95a
commit ee7336c
Show file tree

Hide file tree

Showing 10 changed files with 94 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,10 @@
+---
+project: SimKube
+description: |
+  A collection of tools for saving and replaying running "traces" of a Kubernetes cluster in a simulated environment
+template: docs.html
+---
+
 ![build status](https://github.com/acrlabs/simkube/actions/workflows/verify.yml/badge.svg)
 
 # simkube
@@ -19,9 +26,11 @@ This package provides the following components:
 - `sk-vnode`: a [Virtual Kubelet](https://virtual-kubelet.io)-based "hollow node" that allows customization based off a
   "skeleton" node file (see the example in `simkube/k8s/sk_vnode.py`).
 
-![architecture diagram of SimKube](./docs/images/sk-overview.png)
+### Architecture Diagram
+
+![architecture diagram of SimKube](docs/images/sk-overview.png)
 
-Watch a demo of SimKube:
+### Demo
 
 [![Watch the video](https://img.youtube.com/vi/Q1XpH1H4It8/hqdefault.jpg)](https://www.youtube.com/watch?v=Q1XpH1H4It8)
 
@@ -51,6 +60,7 @@ supported tooling for doing so.
 ### Building
 
 To build all SimKube artifacts for the first time run:
+
 - `git submodule init && git submodule update`
 - `make build` and `make skctl` from the root of this repository.
 
@@ -71,18 +81,6 @@ manifests and deploy all SimKube artifacts to the specified cluster.
 All build artifacts are placed in the `.build/` directory.  You can remove this directory or run `make clean` to clean
 up.
 
-## Documentation
-
-You can find additional documentation  on the individual components in the [docs directory](./docs/) of this repo.
-Links to relevant documentation are below:
-
-- [sk-cloudprov](./docs/sk-cloudprov.md)
-- [skctl](./docs/skctl.md)
-- [sk-ctrl](./docs/sk-ctrl.md)
-- [sk-driver](./docs/sk-driver.md)
-- [sk-tracer](./docs/sk-tracer.md)
-- [sk-vnode](./docs/sk-vnode.md)
-
 ## Contributing
 
 We welcome any and all contributions to the SimKube project!  Please open a pull request.
@@ -96,18 +94,20 @@ issue](https://github.com/acrlabs/simkube/issues)!
 ### Code of Conduct
 
 Applied Computing Research Labs has a strict code of conduct we expect all contributors to adhere to.  Please read the
-[full text](./CODE_OF_CONDUCT.md) so that you understand the expectations upon you as a contributor.
+[full text](https://github.com/acrlabs/simkube/blob/master/CODE_OF_CONDUCT.md) so that you understand the expectations
+upon you as a contributor.
 
 ### Copyright and Licensing
 
-SimKube is licensed under the [MIT License](./LICENSE).  Contributors to this project agree that they own the copyrights
-to all contributed material, and agree to license your contributions under the same terms.  This is "inbound=outbound",
-and is the [GitHub default](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license).
+SimKube is licensed under the [MIT License](https://github.com/acrlabs/simkube/blob/master/LICENSE).  Contributors to
+this project agree that they own the copyrights to all contributed material, and agree to license your contributions
+under the same terms.  This is "inbound=outbound", and is the [GitHub
+default](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license).
 
-> [!WARNING]
-> Due to the uncertain nature of copyright and IP law, this repository does not accept contributions that have been all
-> or partially generated with GitHub Copilot or other LLM-based code generation tools.  Please disable any such tools
-> before authoring changes to this project.
+!!! warning
+    Due to the uncertain nature of copyright and IP law, this repository does not accept contributions that have been all
+    or partially generated with GitHub Copilot or other LLM-based code generation tools.  Please disable any such tools
+    before authoring changes to this project.
 
 ### Contributor's Guide
 

diff --git a/docs/api_changes.md b/docs/api_changes.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # Making API Changes
 
 ## SimKube Custom Resource Definition changes

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # Contributing to SimKube
 
 ## Setting up your environment
@@ -49,16 +54,16 @@ The SimKube repo is organized as follows:
 In general, code that is specific to a single artifact should go in the subdirectory for that artifact, but code that
 needs to be shared between multiple artifacts should go in either `lib/go` or `lib/rust`.
 
-> [!NOTE]
-> If you are planning to make changes to the API (either the Custom Resource Definition or the SimKube API), please read
-> the [API changes](./api_changes.md) document first!
+!!! note
+    If you are planning to make changes to the API (either the Custom Resource Definition or the SimKube API), please read
+    the [API changes](./api_changes.md) document first!
 
 ## Building and Deploying
 
 ### Building the artifacts
 
-To build all SimKube artifacts for the first time run: 
-- `git submodule init && git submodule update` 
+To build all SimKube artifacts for the first time run:
+- `git submodule init && git submodule update`
 - `make build` and `make skctl` from the root of this repository.
 
 For all subsequent builds of SimKube artifacts, run only `make build` and `make skctl` from the root of this repository.
@@ -158,7 +163,7 @@ functions for writing tests.  Feel free to add more utilities in here if it woul
 Go tests live in `_test.go` files next to the source file they are testing.  Rust tests should in most cases be put into
 a separate submodule called `tests` and included with a
 
-```
+```rust
 #[cfg(test)]
 mod tests;
 ```

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -0,0 +1,13 @@
+nav:
+  - Home: README.md
+  - Usage:
+    - Components:
+      - sk-cloudprov: docs/sk-cloudprov.md
+      - sk-ctrl: docs/sk-ctrl.md
+      - sk-driver: docs/sk-driver.md
+      - sk-tracer: docs/sk-tracer.md
+      - sk-vnode: docs/sk-vnode.md
+    - skctl: docs/skctl.md
+  - Contributing:
+    - Developer's Guide: docs/contributing.md
+    - API changes: docs/api_changes.md
diff --git a/docs/sk-cloudprov.md b/docs/sk-cloudprov.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # SimKube Virtual Cloud Provider
 
 SimKube uses the Cluster Autoscaler

diff --git a/docs/sk-ctrl.md b/docs/sk-ctrl.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # SimKube Simulation Controller
 
 The Simulation Controller watches for new Simulation Custom Resources to be posted to the API server and then configures
@@ -35,7 +40,7 @@ The Simulation Controller does the following on receipt of a new Simulation:
 
 Here is an example Simulation object:
 
-```
+```yaml
 apiVersion: simkube.io/v1
 kind: Simulation
 metadata:

diff --git a/docs/sk-driver.md b/docs/sk-driver.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # SimKube Simulation Driver
 
 The SimKube driver is a job that is launched whenever a new simulation is started.  It reads all the contents of a
@@ -34,11 +39,11 @@ Kubernetes control plane whenever a new pod is created.  The mutation endpoint c
 of the simulated resources, and if so, adds the following mutations to the object to ensure that it is scheduled on the
 virtual cluster:
 
-```
+```yaml
 labels:
-  simkube.io/simulation=<simulation-name>
+  simkube.io/simulation: <simulation-name>
 annotations:
-  simkube.io/lifetime-seconds=<pod-lifetime> (if present in the trace)
+  simkube.io/lifetime-seconds: <pod-lifetime> (if present in the trace)
 spec:
   tolerations:
     - key: simkube.io/virtual-node

diff --git a/docs/sk-tracer.md b/docs/sk-tracer.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # SimKube Tracer
 
 The SimKube Tracer runs in a production Kubernetes cluster and watches all configured resources, as well as all pods
@@ -18,8 +23,7 @@ Options:
 
 ## Config File Format
 
-```
----
+```yaml
 trackedObjects:
   <gvk for object>:
     podSpecTemplatePath: /json/patch/path/to/pod/template/spec
@@ -29,8 +33,7 @@ trackedObjects:
 Here is an example config file that watchs both Deployments and VolcanoJobs from the [Volcano](https://volcano.sh/en/)
 Kubernetes scheduler:
 
-```
----
+```yaml
 trackedObjects:
   apps/v1.Deployment:
     podSpecTemplatePath: /spec/template
@@ -58,8 +61,9 @@ in the trace for use by the simulator.
 ## Exporting a trace
 
 A user can export a trace by making a post request to the `/export` endpoint and including a JSON object with the export
-configuration.  The API for this is defined in [`./api/v1/simkube.yml`](./api/v1/simkube.yml).  The response from the
-tracer will be a bytestream of the trace stored in [msgpack](https://msgpack.org) format, which is a JSON-like binary
+configuration.  The API for this is defined in
+[`api/v1/simkube.yml`](https://github.com/acrlabs/blob/master/api/v1/simkube.yml).  The response from the tracer will be
+a bytestream of the trace stored in [msgpack](https://msgpack.org) format, which is a JSON-like binary
 format.  You can inspect the contents of the trace with the `msgpack2json` utility from
 [msgpack-tools](https://github.com/ludocode/msgpack-tools):
 
@@ -80,9 +84,9 @@ The structure of the trace file is a 4-tuple of data:
 
 An entry in the timeseries array looks like this:
 
-```
+```yaml
 {
-    ts: <unix timestamp>
+    ts: <unix timestamp>,
     applied_objs: [array of Kubernetes object definitions],
     deleted_objs: [array of Kubernetes object definitions],
 }
@@ -91,7 +95,7 @@ An entry in the timeseries array looks like this:
 The "tracked object index" (the third entry in the trace) stores the namespaced name of the object along with a hash of
 the object contents.  The pod lifecycle data has the following format:
 
-```
+```yaml
 {
     <pod owner's namespaced name>: {
         <pod hash>: [{start_ts: <unix timestamp>, end_ts: <unix timestamp>}, ...]

diff --git a/docs/sk-vnode.md b/docs/sk-vnode.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # SimKube Virtual Node
 
 The SimKube Virtual Node is build on top of [Virtual Kubelet](https://virtual-kubelet.io) to present a simulated/virtual
@@ -32,7 +37,7 @@ with a node skeleton file that contains all of the properties that node should h
 node object by running `kubectl get -o yaml node test-worker` and modifying accordingly.  Here is an example node
 skeleton that presents as a node with 32GB of RAM and 16 CPUs:
 
-```
+```yaml
 apiVersion: v1
 kind: Node
 status:

diff --git a/docs/skctl.md b/docs/skctl.md
@@ -1,3 +1,8 @@
+---
+project: SimKube
+template: docs.html
+---
+
 # skctl
 
 `skctl` is the CLI for interacting with SimKube.  It's not required to use but it will make your life a lot easier.