Skip to content

Home

Jump to bottom
mattrowe-opennebula edited this page Apr 1, 2026 · 7 revisions

OpenNebula Documentation

Welcome to the OpenNebula documentation repository.

This repository contains the documentation for the OpenNebula system. The documentation is updated here as part of a Docs-as-Code process to keep the documentation in line with the evolving OpenNebula system.

Creating and Editing Documentation

The OpenNebula documentation is written using numerous guidelines and standards. The following pages give style and formatting guidance for different documentation aspects:

Quick Reference

The following details a recommended workflow for creating new documentation.

1. Consider the type of documentation you are creating:

Which document type are you creating? Refer to the Document Type Guide and consider the following things:

  • Who is it for?

    • A new user or an advanced user?
    • An engineer or an administrator?

  • What is the aim of the documentation?

    • Describe concepts or system architecture - Explanatory documentation
    • Teaching a user how to do something new - Tutorial
    • Describing a procedure for an advanced user to achieve a specific aim - How-to guide
    • Outlining arguments or parameters of an API - Reference

2. Structure the document

Consider how to structure the document following the Document Structure Guide. Keep in mind the following considerations:

  • Include an introduction that states the aim of the documentation
  • Follow a linear structure as much as possible - i.e. a single execution path, avoid options where possible
  • Fix versions: avoid advising the user to "install the latest version" since future versions might change or break functionality

3. Include images, code and CLI commands as needed

Images

Include screenshots to show the user UI elements they should use or demonstrate what they should see after an operation. High resolution PNG is preferred for screenshots. Include conceptual or system diagrams if needed, preferably in SVG format.

Use the image shortcode syntax to include the image:

{{< image path="/images/ISO/00-onepoc_arch.svg" alt="OnePOC Arch" align="center" width="80%" >}}

We recommend that the images are normally centered and cover a maximum of 80%-90% of the container, which makes the text easier to follow.

Code and CLI commands

Code and CLI commands can be added to the document using the Fenced Codeblock Syntax. The codeblock is opened and closed by three backticks - ``` - you should also include the intended highlighting style after the openning backticks. Refer to the Code and Command Line Guide for more details.

Examples:

CLI command:

```shell
onevm terminate --hard <ID>
```

CLI output:

```default
### Report
OpenNebula 7.0 was installed
Sunstone is running on:
  http://192.168.1.130/
Use following to login:
  user: oneadmin
  password: ZMCoOWUsBg
```

JSON file:

```json
{
  "VM": {
    "NAME": "service_1",
    "ID": "9",
    "TEMPLATE": {"NIC": []}
  }
}
```

Documentation Versioning

Versioning of the documentation is achieved using separate branches for each release, while the latest documentation is maintained in the master branch. The documentation corresponding to the most recent versions of OpenNebula is contained is maintained in the following branches:

Maintenance branches are used for maintenance releases of major version updates. Dopcumentation related to bug fixes and backported features from later versions are included in the maintenance branches. Maintenace branches are merged into their respective major branches upon the release of a maintenance update.

The documentation for versions 6.10 and lower is maintained in a separate repository.

Clone this wiki locally