We more than welcome contributions to KubeVirt documentation. Please reach out if you happen to have an idea or find an issue with our contents!

You can find the markdown that powers the user guide in ./docs, most commits are to that area.

We use mkdocs markdown engine with mkdocs-awesome-pages plugin

• mkdocs config file
• Each subdirectory of ./docs contains a .pages file. We use this to force the ordering of pages. Alphabetical ordering is not ideal for technical documentation.

Signature verification on commits are required -- you may sign your commits by running:

$ git commit -s -m "The commit message" file1 file 2 ...

If you need to sign all commits from a certain point (for example, master), you may run:

git rebase --exec 'git commit --amend --no-edit -n -s' -i master

Signed commit messages generally take the following form:

<your commit message> Signed-off-by: <your configured git identity> 

$ make check_spelling $ make check_links $ make build_img $ make run

NOTE If you use docker you may need to set CONTAINER_ENGINE and BUILD_ENGINE:

$ export CONTAINER_ENGINE=docker $ export BUILD_ENGINE=docker $ make run

Open your web browser to http://0.0.0.0:8000 and validate page rendering

After you have vetted your changes, make a PR to kubevirt/user-guide so that others can review.

Makefile for user-guide mkdocs application Usage:  make <target> Env Variables:  CONTAINER_ENGINE Set container engine, [*podman*, docker]  BUILD_ENGINE Set build engine, [*podman*, buildah, docker]  SELINUX_ENABLED Enable SELinux on containers, [*False*, True]  LOCAL_SERVER_PORT Port on which the local mkdocs server will run, [*8000*] Targets:  help Show help  check_links Check external and internal links  check_spelling Check spelling on site content  build_img Build image: userguide  build_image_yaspeller Build image: yaspeller  build Build site. This target should only be used by Prow jobs.  run Run site. App available @ http://0.0.0.0:8000  status Container status  stop Stop site  stop_yaspeller Stop yaspeller image

• CONTAINER_ENGINE: Some of us use docker. Some of us use podman (default: podman).

• BUILD_ENGINE: Some of us use docker. Some of us use podman or buildah (default: podman).

• SELINUX_ENABLED: Some of us run SELinux enabled. Set to True to enable container mount labelling.

• PYTHON: Change the python executable used (default: python3.7).

• PIP: Change the pip executable used (default: pip3).

• LOCAL_SERVER_PORT: Port on which the local mkdocs server will run, i.e. http://localhost:<port> (default: 8000).

• DEBUG: This is normally hidden. Set to True to echo target commands to terminal.

• check_links: HTMLProofer is used to check any links to external websites as we as any cross-page links

• check_spelling: yaspeller is used to check spelling. Feel free to update to the dictionary file as needed (kubevirt/project-infra/images/yaspeller/.yaspeller.json).

• build_img: mkdocs project does not provide a container image. Use this target to build an image packed with python and mkdocs app. ./docs will be mounted. ./site will be mounted as tmpfs...changes here are lost.

• build_image_yaspeller: yaspeller project does not provide a container image. User this target to Build an image packed with nodejs and yaspeller app. ./docs will be mounted. yaspeller will check content for spelling and other bad forms of English.

• status: Basically ${BUILD_ENGINE} ps for an easy way to see what's running.

• stop: Stop container and app

• stop_yaspeller: Sometimes yaspeller goes bonkers. Stop it here.

• File a bug: https://github.com/kubevirt/user-guide/issues

• Mailing list: https://groups.google.com/forum/#!forum/kubevirt-dev

• Slack: https://kubernetes.slack.com/messages/virtualization

• Start contributing: https://kubevirt.io/user-guide/appendix/contributing

• Check our privacy policy at: https://kubevirt.io/privacy/

• We do use https://netlify.com Open Source Plan for rendering Pull Requests to the documentation repository