Update docs based on style guide

[afritzler]

Summary by CodeRabbit

• Documentation

  • Fixed grammatical errors, typos, and wording inconsistencies across docs
  • Updated relative links to absolute paths for improved navigation
  • Expanded contributor guidance with clearer steps and commands
  • Added a local-setup visual and clarified usage examples
  • Clarified technical prose and examples for several architecture and usage topics

• Style

  • Standardized heading formats and capitalization
  • Unified code-block language tags and markdown formatting conventions

[coderabbitai]

Warning

Rate limit exceeded

@afritzler has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 25 minutes and 21 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

This pull request makes widespread documentation edits (typos, grammar, wording, link path and heading adjustments) across baremetal, IaaS, community, network-automation, and overview docs, and applies three small source changes in src/calculator.py (new method, signature change, variable rename).

Changes

Cohort / File(s)	Summary
Calculator source changes src/calculator.py	Added coderabbit_add(x, y); updated coderabbit_formula(x, y) → coderabbit_formula(x, y, z); renamed global variable old_global_var → new_global_var. Review for call sites and tests.
Link path updates docs/baremetal/operations-guide/overview.md, docs/iaas/operations-guide/overview.md, docs/iaas/usage-guides/index.md	Replaced relative links with absolute paths (Troubleshooting, API References). Check navigation and CI link validation.
Baremetal docs docs/baremetal/api-references/index.md, docs/baremetal/architecture/discovery.md, docs/baremetal/architecture/index.md, docs/baremetal/architecture/maintenance.md, docs/baremetal/architecture/provisioning.md, docs/baremetal/index.md	Editorial fixes: wording, formatting, minor phrasing removals and typo corrections.
Baremetal Kubernetes docs/baremetal/kubernetes/cloud-controller-manager.md, docs/baremetal/kubernetes/gardener.md	Grammar, terminology, capitalization, and small phrasing corrections.
IaaS architecture docs/iaas/architecture/networking.md, docs/iaas/architecture/providers/brokers.md, docs/iaas/architecture/providers/ceph-provider.md, docs/iaas/architecture/providers/libvirt-provider.md, docs/iaas/architecture/runtime-interface.md, docs/iaas/architecture/scheduling.md	Typo fixes, wording/formatting changes; libvirt-provider diagram expanded.
IaaS Kubernetes docs/iaas/kubernetes/cloud-controller-manager.md, docs/iaas/kubernetes/csi-driver.md, docs/iaas/kubernetes/index.md	Editorial rewrites, capitalization and punctuation corrections; no API changes.
IaaS usage guides docs/iaas/usage-guides/compute.md, docs/iaas/usage-guides/storage.md	Capitalization normalization (MachineClasses, VolumeClasses, BucketClasses), minor wording and formatting updates.
Getting Started docs/iaas/getting-started.md	Title and wording tweaks; code fence languages changed to shell; image added; example links updated to use refs/heads/main.
Contributing guide docs/community/contributing.md	Expanded contribution steps: branch examples, commit/DCO guidance, test/lint commands; removed numeric prefixes in headings.
Network-automation & overview docs/network-automation/index.md, docs/overview/index.md, docs/overview/principles.md	Wording tense adjustments, singularization of feature label, heading simplification, and hyperlink formatting.
Other docs editorial docs/baremetal/..., docs/iaas/..., docs/* (various listed in summary)	Multiple other minor editorial and formatting fixes across documentation files (grammar, hyphenation, backtick removal, typo corrections).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

documentation

Suggested reviewers

• felix-kaestner

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is missing; no content was provided by the author beyond the auto-generated PR metadata.	Add a description following the template with: 1) Proposed Changes (document/section updates and rationale), 2) Issue reference if applicable. Include brief context about the style guide updates.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main objective of the PR—updating documentation to align with the project's style guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch enh/harmonize-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[afritzler]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 7

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/community/contributing.md (1)

53-58: ⚠️ Potential issue | 🟡 Minor

Add a brief note to set up the upstream remote before rebase.

git fetch upstream main assumes an existing upstream remote; many first-time contributors won’t have it. Add a short setup snippet or a conditional note to prevent confusion.

✏️ Suggested doc tweak

 If needed, rebase to the current `main` before submitting your pull request:
 
 ```shell
+git remote add upstream git@github.com:ironcore-dev/<repository>.git
 git fetch upstream main
 git rebase upstream/main

</details>

</blockquote></details>

</blockquote></details>

🤖 Fix all issues with AI agents

In `@docs/iaas/architecture/networking.md`:
- Line 30: Fix the wording in the documentation entry for the "apinetlet"
component: change the phrase "responsible from translating" to "responsible for
translating" in the sentence that describes apinetlet translating user-facing
API objects from the `networking` resource group into the internal
representation used by `ironcore-net` so the preposition is correct.
- Line 71: Fix the duplicated article in the sentence referencing MachineRuntime
by removing the extra "the" so it reads "the corresponding
`AttachNetworkInterface`"; update the text that currently reads "the
corresponding the `AttachNetworkInterface`" to "the corresponding
`AttachNetworkInterface`" in the docs line that mentions the
`AttachNetworkInterface` method on the `MachineRuntime` interface.
- Line 27: Update the phrase "network related decisions" in the text to the
hyphenated compound adjective "network-related decisions" so the compound
adjective correctly precedes the noun; locate the occurrence in the line
containing "the place where all network related decisions like reservation of
unique IP addresses, allocation of unique network IDs, etc. are made." and
replace it with "network-related decisions".
- Line 84: Change the verb to match the singular subject "the `metalnetlet`":
update the sentence so the `metalnetlet` "creates" (not "create") the
corresponding `LoadBalancer` or `NATGateway` objects in the `metalnet` API,
i.e., replace "and create the corresponding `LoadBalancer` or `NATGateway`
objects in the `metalnet` API." with "and creates the corresponding
`LoadBalancer` or `NATGateway` objects in the `metalnet` API."

In `@docs/iaas/architecture/providers/ceph-provider.md`:
- Around line 10-12: Remove the duplicated article "A" between the two sentences
describing the ceph-volume-provider: edit the sentence that currently reads "A A
`CreateVolume` IRI call..." so it becomes a single "A `CreateVolume` IRI
call..." (reference strings: "ceph-volume-provider" and "`CreateVolume` IRI") to
eliminate the double "A" and keep the sentence grammatically correct.

In `@docs/iaas/architecture/scheduling.md`:
- Around line 14-16: Replace the unhyphenated phrase "network related
components" with "network-related components" in the scheduling doc; search for
the exact string "network related components" (in the paragraph that mentions
the `networking` API and the [networking section]) and update it to use the
hyphenated form.

In `@docs/iaas/usage-guides/storage.md`:
- Around line 86-88: Replace all inconsistent casings of the provider field so
the docs use the API's actual field name providerId (camelCase) everywhere;
update occurrences of providerID and ProviderID to providerId in the VolumePool
and BucketPool sections (and any other mentions around the noted locations) so
examples, descriptions, and field lists consistently reference providerId.

🧹 Nitpick comments (4)

docs/overview/index.md (1)

9-9: Consider hyphenating compound adjectives.

When "bare metal management" and "network automation" are used attributively to modify "layers", standard English style guides recommend hyphenation: "bare-metal management" and "network-automation". This would read: "The bare-metal management and network-automation layers belong to..."

However, if your style guide treats these as proper names that remain unhyphenated even when used attributively, the current form is acceptable.

📝 Optional edit for compound adjective hyphenation

-The following diagram shows IronCore's two layers. The bare metal management and network automation layers
+The following diagram shows IronCore's two layers. The bare-metal management and network-automation layers

docs/baremetal/architecture/maintenance.md (1)

5-6: Reconsider removing the bullet list formatting.

The markdown list formatting was removed from the TODO items. Keeping these as a bulleted list would improve readability and make it clearer that these are distinct action items.

♻️ Restore bullet list formatting

 TODO:
 
-- Describe the maintenance process
-- Describe the extension points here
+- Describe the maintenance process
+- Describe the extension points here

docs/iaas/kubernetes/csi-driver.md (1)

50-109: Editorial improvements enhance consistency.

The capitalization of method names and resource types (e.g., CreateVolume, Volume, Node) aligns with Kubernetes documentation conventions and improves readability.

Optional: Consider varying repetitive phrasing.

The phrase "is called when a volume needs to be" appears in lines 70, 78, 89, 96, and 105. Consider rephrasing some instances for variety, such as:

• "is invoked to"
• "handles the task of"
• "is triggered when"

This is a minor stylistic suggestion and does not affect technical accuracy.

docs/iaas/kubernetes/cloud-controller-manager.md (1)

40-40: Optional: Consider hyphenating "cloud-provider-specific."

The phrase "cloud provider specific APIs" could use a hyphen: "cloud-provider-specific APIs" to form a compound adjective. This is a minor stylistic suggestion.