Add examples, concepts, and getting started documentation - #24
Add examples, concepts, and getting started documentation#24abdelrahman-attala wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
We need to mention here the installation method using helm repo and helm chart. this is like way around
| @@ -0,0 +1,15 @@ | |||
| # Examples | |||
|
|
|||
| This section provides simple examples of the three main Koptan resources: | |||
There was a problem hiding this comment.
Explain the relations and dependency more between the three phases
| ## Implementation Clues in the Repository | ||
|
|
||
| Relevant files include: | ||
|
|
||
| - `api/v1alpha/voyage_types.go` | ||
| - `internal/controller/voyage_controller.go` |
There was a problem hiding this comment.
| ## Implementation Clues in the Repository | |
| Relevant files include: | |
| - `api/v1alpha/voyage_types.go` | |
| - `internal/controller/voyage_controller.go` |
|
|
||
| Koptan currently introduces the following main custom resources: | ||
|
|
||
| - **GoApp** |
There was a problem hiding this comment.
Put the app types under a category App
There was a problem hiding this comment.
Please add a chart or draw here. Showing this in visual way
| nav: | ||
| - Home: index.md | ||
| - Overview: overview.md | ||
|
|
||
| - Concepts: | ||
| - Overview: concepts/index.md | ||
| - Apps: concepts/apps.md | ||
| - Slipway: concepts/slipway.md | ||
| - Voyage: concepts/voyage.md | ||
|
|
||
| - Getting Started: | ||
| - Overview: getting-started/index.md | ||
| - Installation: getting-started/installation.md | ||
| - Quickstart: getting-started/quickstart.md | ||
|
|
||
| - Examples: | ||
| - Overview: examples/index.md | ||
| - App Example: examples/app.md | ||
| - Slipway Example: examples/slipway.md | ||
| - Voyage Example: examples/voyage.md |
There was a problem hiding this comment.
Is this really needed?!
| nav: | |
| - Home: index.md | |
| - Overview: overview.md | |
| - Concepts: | |
| - Overview: concepts/index.md | |
| - Apps: concepts/apps.md | |
| - Slipway: concepts/slipway.md | |
| - Voyage: concepts/voyage.md | |
| - Getting Started: | |
| - Overview: getting-started/index.md | |
| - Installation: getting-started/installation.md | |
| - Quickstart: getting-started/quickstart.md | |
| - Examples: | |
| - Overview: examples/index.md | |
| - App Example: examples/app.md | |
| - Slipway Example: examples/slipway.md | |
| - Voyage Example: examples/voyage.md |
There was a problem hiding this comment.
Pull request overview
Adds foundational MkDocs documentation for Koptan, including overview/concepts, a getting-started flow, and example manifests to help users understand and adopt the CRDs.
Changes:
- Expanded
mkdocs.ymlwith richer theme configuration and a structured nav for Overview/Concepts/Getting Started/Examples. - Added new docs pages under
docs/concepts/,docs/getting-started/,docs/examples/, plus a top-leveldocs/overview.md. - Introduced example YAML manifests for App/Slipway/Voyage resources.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds site metadata, theme features, plugins, and navigation for new documentation sections. |
| docs/overview.md | High-level overview of Koptan’s purpose and main CRDs. |
| docs/concepts/index.md | Entry page for the Concepts section. |
| docs/concepts/apps.md | Describes App resource types and where they live in the repo. |
| docs/concepts/slipway.md | Describes Slipway’s role and points to relevant implementation files. |
| docs/concepts/voyage.md | Describes Voyage’s role and points to relevant implementation files. |
| docs/getting-started/index.md | Entry page for Getting Started. |
| docs/getting-started/installation.md | Installation instructions for CRDs/operator (currently has a rendering issue). |
| docs/getting-started/quickstart.md | Minimal “create an App” walkthrough (currently has correctness/rendering issues). |
| docs/examples/index.md | Explains the typical workflow and links to examples. |
| docs/examples/app.md | Example manifests for GoApp/JavaApp/DotnetApp. |
| docs/examples/slipway.md | Slipway example manifests (currently missing required fields). |
| docs/examples/voyage.md | Voyage example manifests (currently has major markdown structure issues). |
Comments suppressed due to low confidence (1)
docs/getting-started/installation.md:21
- The bash code fence is opened but never closed, which will break the rest of the page rendering. Add a closing triple-backtick after the
kubectl applycommand.
```bash
kubectl apply -k config/crd
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| A minimal example is shown below: | ||
|
|
||
| ```yaml | ||
| apiVersion: koptan.felukka.sh/v1alpha1 |
There was a problem hiding this comment.
The Quickstart YAML uses apiVersion: koptan.felukka.sh/v1alpha1, but the CRDs in this repo are registered under koptan.felukka.org/v1alpha (see api/v1alpha/groupversion_info.go). Update the example to the correct group/version so it can be applied successfully.
| apiVersion: koptan.felukka.sh/v1alpha1 | |
| apiVersion: koptan.felukka.org/v1alpha |
| metadata: | ||
| name: example-goapp | ||
| spec: | ||
| {} |
There was a problem hiding this comment.
GoAppSpec requires spec.source (with at least repo), but this example uses spec: {} which will fail validation/admission. Update the minimal example to include spec.source.repo (and optionally revision).
| {} | |
| source: | |
| repo: https://github.com/my-org/my-go-app.git | |
| revision: main |
| ```yaml | ||
| apiVersion: koptan.felukka.sh/v1alpha1 | ||
| kind: GoApp |
There was a problem hiding this comment.
The YAML code fence is opened but never closed, which will break page rendering in MkDocs. Add a closing triple-backtick after the example manifest.
| ```yaml | ||
| apiVersion: koptan.felukka.org/v1alpha | ||
| kind: Slipway | ||
| metadata: | ||
| name: feedme | ||
| spec: | ||
| appRef: | ||
| name: feedme | ||
| kind: GoApp | ||
| ``` |
There was a problem hiding this comment.
SlipwaySpec requires spec.image (registry/name, etc.), but these examples only include spec.appRef. As written they won't pass CRD validation. Include a minimal spec.image block in each Slipway example (or adjust the text to state the omitted fields are required).
| --- | ||
|
|
||
| # 📄 `docs/examples/voyage.md` | ||
|
|
||
| ```md | ||
| # Voyage Example |
There was a problem hiding this comment.
This page starts with a bare --- and then wraps all content inside a fenced ```md block plus a file-path heading. That structure is inconsistent with the other docs pages and also results in broken markdown (the md fence is never closed). Remove the wrapper/front-matter placeholder and make the page a normal markdown document starting with `# Voyage Example`.
| ```bash | ||
| kubectl apply -f voyage.yaml No newline at end of file |
There was a problem hiding this comment.
The final bash snippet opens a fenced block but never closes it, so MkDocs will treat the rest of the file as code. Add a closing triple-backtick after the kubectl apply command.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (2)
docs/getting-started/installation.md:21
- The shell snippet code block is opened but not closed. Add the closing code fence so the page renders correctly.
```bash
kubectl apply -k config/crd
docs/getting-started/quickstart.md:25
- The YAML code block is opened but never closed, which will cause the rest of the page (and potentially subsequent Markdown rendering) to be treated as code. Add the closing fence after the manifest.
```yaml
apiVersion: koptan.felukka.sh/v1alpha1
kind: GoApp
metadata:
name: example-goapp
spec:
{}
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| apiVersion: koptan.felukka.org/v1alpha | ||
| kind: Slipway | ||
| metadata: | ||
| name: feedme | ||
| spec: | ||
| appRef: | ||
| name: feedme | ||
| kind: GoApp | ||
| ``` |
There was a problem hiding this comment.
SlipwaySpec requires spec.image (registry/name), but the examples omit it, so these manifests won’t validate/apply. Please include the required image fields in the Slipway examples.
| ```bash | ||
| kubectl apply -f slipway.yaml No newline at end of file |
There was a problem hiding this comment.
The kubectl apply snippet code block is opened but not closed. Add the closing fence so the rest of the page renders normally.
review ba2a