Repository files navigation

You can find the docs here:https://docs.testkube.io

System requirements:

• npm

If you're editing the docs, follow this workflow:

1. Install dependencies withnpm install
2. Spin up local development withnpm run start, add-- --port XXXX if you need to change the default port (3000)
3. Update the docs inside the/docs folder
4. Make sure to add the new document in thesidebar.json file:

{  type: "category",  label: "Concepts",  items: [    {      type: "category",      label: "Tests",      items: [        "concepts/tests/tests-creating",        "concepts/tests/tests-running",        "concepts/tests/tests-getting-results",        "concepts/tests/tests-variables",+       "concepts/new-concept"      ],    },}

Also make sure the documentation builds ok locally before opening a PR - this will check for broken links, etc.

npm run build

5. You can preview the changes locally in your browser:http://localhost:3000

If you want to add a warning/info message like the below, useDocusuarus Admonitions.

If the content of the code blocks refers to a file, use DocusaurusCode Block title.

Don't:

file.js```jsfile;content;```

Do:

```js title="file.js"file;content;```

You can create tabs for structuring your content, for example as in theCLI Installation page.

Please note that headlines inside tab content will be shown in the navigation menu to the right, but will notwork as direct links from external sources unless they are under the default/first tab.

For search, we've indexed all the pages into 3 distinct categoriesMain,Reference andLegacy.By default theMain index is used which contains all the results which haven't been included in the other 2 indexes.The user can switch between indexes by clicking one of the 3 options at the top for the search bar.

All docs pages which haven't been explicitly included in the other indexes, are part of theMain index.To add a page to a specific index, add the following meta tag in the head of the page. e.g:<meta name="docsearch:indexPrefix" content="YOUR_INDEX" />

These docs useredocusaurus to generate OpenAPI documentation, butsince the Testkube OpenAPI definitions are too large (resulting invery long build/rendering times), there is asmall script atsrc/scripts/split-openapis.ts that:

• retrieves the OpenAPI definitions for both the agent and control plane APIs
• splits them into smaller definitions into thesrc/openapi folder
• generates corresponding mdx files into thedocs/openapi folder
• generatessrc/opeanpi/../redoc-sidebar.js files that are included into the mainsidebar.js config to add thegenerated mdx files to the sidebar navigation
• generatessrc/openapi/../redoc-specs.js files that are included into thedocusaurus.config.js config toadd the generated specs to the redocusaurs configuration

The script requires a GitHub Access Token to be provided in a TESTKUBE_OPENAPI_GITHUB_ACCESS_TOKEN environment variablefor retrieving the Control Plane OpenAPI definition from its private repo.

This script needs to be run every time the openapi definition is updated to regenerate the docs accordingly:

npm run split-openapis

Once run, the generated/updated files need to be committed back to the repo for the automated build to publish them.

CRD references docs at are generated from the corresponding GoLang types using a fork of thehttps://github.com/elastic/crd-ref-docs project, available athttps://github.com/kubeshop/crd-ref-docs.

The customized markdown templates are in this repositoriessrc/crd-templates folder

Follow these steps:

1. Clone/update thetestkube-operatormain branch to make sure you have the latest types available locally.
2. Clone thehttps://github.com/kubeshop/crd-ref-docs repo
3. Make sure you have go tooling installed and rungo build in this repo, thisshould create acrd-ref-docs binary in the roof folder of the repo.
4. Set the desired Kubernetes Version to use for outgoing links to reference docs in theconfig.yaml file (at least v1.28)
5. Create adocs folder in the cloned repo and now run the following command (using thecrd-ref-docs tool):

./crd-ref-docs  --source-path=<path to testestkube-operator project>  --config=config.yaml  --renderer=markdown  --output-path=./docs  --output-mode=group  --templates-dir=<testkube-docs-root>/src/crd-templates

For example:

 ./crd-ref-docs --source-path=/Users/olensmar/GolandProjects/testkube-operator --config=config.yaml --renderer=markdown --output-path=./docs --output-mode=group --templates-dir=/Users/olensmar/WebstormProjects/testkube-docs/src/crd-templates2024-08-05T11:44:21.019+0200    INFO    crd-ref-docs    Loading configuration   {"path":"config.yaml"}2024-08-05T11:44:21.020+0200    INFO    crd-ref-docs    Processingsource directory     {"directory":"/Users/olensmar/GolandProjects/testkube-operator","depth": 10}2024-08-05T11:44:22.717+0200    INFO    crd-ref-docs    Rendering output        {"path":"./docs"}2024-08-05T11:44:22.790+0200    INFO    crd-ref-docs    CRD reference documentation generated2024-08-05T11:44:22.790+0200    INFO    crd-ref-docs    Execution time: 1.770360541s

Thedocs folder should now contain the generated files:

➜  crd-ref-docs git:(master) ✗ ls -l docstotal 152-rw-r--r-- 1 olensmar  8737 Aug  5 11:44 executor.testkube.io-v1.md-rw-r--r-- 1 olensmar 45172 Aug  5 11:44 tests.testkube.io-v1.md-rw-r--r-- 1 olensmar 10369 Aug  5 11:44 tests.testkube.io-v2.md-rw-r--r-- 1 olensmar 19695 Aug  5 11:44 tests.testkube.io-v3.md-rw-r--r-- 1 olensmar 60601 Aug  5 11:44 testworkflows.testkube.io-v1.md

6. Copy these files to the/docs/articles/crds folder in this repo
7. Make sure the links and info in/docs/articles/crds.md is correct and up to date
8. Add the deprecation warning after the main headline in all files containing deprecated APIs:

#Testkube API Referenceimport LegacyWarning from '../\_legacy-warning.mdx';<LegacyWarning />

9. Create a branch, commit and create a PR

The CLI docs are generated in theTestkube Repo by running

make docs

in the root folder and copying the generated files from thegen/docs/cli folder to the/docs/cli folder in this repo (clear the folder first so old files are removed).

:::tipMake sure the generated docs build withnpm run build ok before committing, and fix any errors manually as applicable.:::