Skip to content

Commit d21257a

Browse files
afritzlerafritzler
committed
Switch docs to vitepress
Use vitepress to generate and publish our project documentation. The github action has been changed to also use vitepress to publish the documentation content as GH pages. The current dev setup has been kept in takt by running `make startdocs` locally.
1 parent 8261698 commit d21257a

File tree

11 files changed

+4167
-35
lines changed

11 files changed

+4167
-35
lines changed

‎.github/dependabot.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,7 @@ updates:
2424
directory: "/"
2525
schedule:
2626
interval: "weekly"
27+
- package-ecosystem: "npm"
28+
directory: "/docs"
29+
schedule:
30+
interval: "weekly"

‎.github/workflows/publish-docs.yml‎

Lines changed: 55 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,64 @@
1-
name: Publish docs via GitHub Pages
1+
name: Deploy VitePress site to Pages
2+
23
on:
4+
# Runs on pushes targeting the `main` branch. Change this to `master` if you're
5+
# using the `master` branch as the default branch.
36
push:
4-
branches:
5-
- main
7+
branches: [main]
8+
9+
# Allows you to run this workflow manually from the Actions tab
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
613
permissions:
7-
contents: write
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
824
jobs:
9-
deploy:
10-
name: Deploy docs
25+
# Build job
26+
build:
1127
runs-on: ubuntu-latest
1228
steps:
13-
- name: Checkout main
29+
- name: Checkout
1430
uses: actions/checkout@v4
15-
- name: Configure Git Credentials
16-
run: |
17-
git config user.name github-actions[bot]
18-
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
19-
- uses: actions/setup-python@v5
2031
with:
21-
python-version: 3.x
22-
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
23-
- uses: actions/cache@v4
32+
fetch-depth: 0 # Not needed if lastUpdated is not enabled
33+
# - uses: pnpm/action-setup@v3 # Uncomment this block if you're using pnpm
34+
# with:
35+
# version: 9 # Not needed if you've set "packageManager" in package.json
36+
# - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
37+
- name: Setup Node
38+
uses: actions/setup-node@v4
39+
with:
40+
node-version: 24
41+
cache: npm # or pnpm / yarn
42+
- name: Setup Pages
43+
uses: actions/configure-pages@v4
44+
- name: Install dependencies
45+
run: npm ci # or pnpm install / yarn install / bun install
46+
- name: Build with VitePress
47+
run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
48+
- name: Upload artifact
49+
uses: actions/upload-pages-artifact@v3
2450
with:
25-
key: mkdocs-material-${{ env.cache_id }}
26-
path: .cache
27-
restore-keys: |
28-
mkdocs-material-
29-
- run: pip install mkdocs-material
30-
- name: Deploy docs
31-
run: mkdocs gh-deploy --force
32-
env:
33-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
51+
path: docs/.vitepress/dist
52+
53+
# Deployment job
54+
deploy:
55+
environment:
56+
name: github-pages
57+
url: ${{ steps.deployment.outputs.page_url }}
58+
needs: build
59+
runs-on: ubuntu-latest
60+
name: Deploy
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,6 @@ go.work
2727
*.swo
2828
*~
2929
.idea/
30+
node_modules/
31+
.vitepress
32+
.cache

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ lint-config: golangci-lint ## Verify golangci-lint linter configuration
125125
.PHONY: startdocs
126126
startdocs: ## Start the local mkdocs based development environment.
127127
docker build -t $(IMAGE) -f docs/Dockerfile . --load
128-
docker run -p 9000:9000 -v `pwd`/:/docs $(IMAGE)
128+
docker run -p 5173:5173 -v `pwd`/docs:/app $(IMAGE)
129129

130130
.PHONY: cleandocs
131131
cleandocs: ## Remove all local mkdocs Docker images (cleanup).

‎docs/Dockerfile‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
1-
FROM squidfunk/mkdocs-material:latest
1+
FROM node:24-alpine
22

3-
LABEL project=metal_operator
3+
# Install bash (optional but useful)
4+
RUN apk add --no-cache bash
45

5-
WORKDIR /docs
6+
# Set working directory
7+
WORKDIR /app
68

7-
COPY docs/requirements.txt requirements.txt
8-
RUN pip install --no-cache-dir -r requirements.txt
9+
# Install vitepress globally (optional, npx will work too)
10+
RUN npm install -g vitepress
11+
RUN npm install -g vitepress-plugin-mermaid
912

10-
EXPOSE 9000
13+
# Expose dev port
14+
EXPOSE 5173
1115

12-
# Start development server by default
13-
ENTRYPOINT ["mkdocs"]
14-
CMD ["serve", "--dev-addr=0.0.0.0:9000"]
16+
# Default command to start VitePress dev
17+
CMD ["npx", "vitepress", "dev", "--host", "0.0.0.0"]

‎docs/architecture.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Metal-Operator Architectural Description
22

3-
The **metal-operator** is a Kubernetes operator designed to manage bare metal servers within a Kubernetes environment. It automates the provisioning, configuration, and lifecycle management of physical servers by integrating them into Kubernetes using Custom Resource Definitions (CRDs) and controllers. The architecture promotes modularity, scalability, and flexibility, enabling seamless integration with various boot mechanisms and provisioning tools.
3+
The **metal-operator** is a Kubernetes operator designed to manage bare metal servers within a Kubernetes environment.
4+
It automates the provisioning, configuration, and lifecycle management of physical servers by integrating them into
5+
Kubernetes using Custom Resource Definitions (CRDs) and controllers. The architecture promotes modularity, scalability,
6+
and flexibility, enabling seamless integration with various boot mechanisms and provisioning tools.
47

58
## Architectural Diagram
69

@@ -73,6 +76,7 @@ flowchart LR
7376
- [**Server**](concepts/servers.md): Represents physical servers, managing their state, power, and configurations.
7477
- [**ServerClaim**](concepts/serverclaims.md): Allows users to reserve servers by specifying desired configurations and boot images.
7578
- [**ServerBootConfiguration**](concepts/serverbootconfigurations.md): Signals the need to prepare the boot environment for a server.
79+
- [**ServerMaintenance**](concepts/servermaintenance.md): Represents maintenance tasks for servers, such as BIOS updates or hardware repairs.
7680
- [**BIOSSettings**](concepts/biossettings.md): Handles updating the BIOS setting on the physical server's BIOS.
7781
- [**BIOSVersion**](concepts/biosversion.md): Handles upgrading the BIOS Version on the physical server's BIOS.
7882
- [**BMCSettings**](concepts/bmcsettings.md): Handles updating the BMC setting on the physical server's Manager.

‎docs/concepts/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Concepts
2+
3+
This section provides an overview of the key concepts in the Metal Operator API, detailing the primary resources and
4+
their relationships. Each concept is linked to its respective documentation for further reading.
5+
6+
- [**Endpoint**](/concepts/endpoints): Represents devices on the out-of-band management network, identified by MAC and IP addresses.
7+
- [**BMC**](/concepts/bmcs): Models Baseboard Management Controllers (BMCs), allowing interaction with server hardware.
8+
- [**BMCSecret**](/concepts/bmcsecrets): Securely stores credentials required to access BMCs.
9+
- [**Server**](/concepts/servers): Represents physical servers, managing their state, power, and configurations.
10+
- [**ServerClaim**](concepts/serverclaims.md): Allows users to reserve servers by specifying desired configurations and boot images.
11+
- [**ServerBootConfiguration**](concepts/serverbootconfigurations.md): Signals the need to prepare the boot environment for a server.
12+
- [**ServerMaintenance**](concepts/servermaintenance.md): Represents maintenance tasks for servers, such as BIOS updates or hardware repairs.
13+
- [**BIOSSettings**](concepts/biossettings.md): Handles updating the BIOS setting on the physical server's BIOS.
14+
- [**BIOSVersion**](concepts/biosversion.md): Handles upgrading the BIOS Version on the physical server's BIOS.
15+
- [**BMCSettings**](concepts/bmcsettings.md): Handles updating the BMC setting on the physical server's Manager.
16+
- [**BMCVersion**](concepts/bmcversion.md): Handles upgrading the BMC Version on the physical server's Manager.

‎docs/index.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
# https://vitepress.dev/reference/default-theme-home-page
3+
layout: home
4+
5+
hero:
6+
name: "Metal Operator"
7+
text: "Kubernetes operator to automate bare metal servers"
8+
tagline: My great project tagline
9+
image:
10+
src: https://raw.githubusercontent.com/ironcore-dev/ironcore/refs/heads/main/docs/assets/logo_borderless.svg
11+
alt: VitePress
12+
actions:
13+
- theme: brand
14+
text: Getting started
15+
link: /usage/installation
16+
- theme: alt
17+
text: API Reference
18+
link: /api-reference/api
19+
20+
features:
21+
- title: 🚀 Automatic Server Discovery and Provisioning
22+
details: Disvover and provision bare metal servers automatically
23+
- title: 🚧 Day 2 Operations
24+
details: Manage BIOS and Firmware updates, hardware inventory, and more
25+
- title: 💕 Kubernetes Native API
26+
details: Kubernetes native API for managing bare metal servers
27+
---
28+

0 commit comments

Comments
 (0)