Contribute to these docs

These docs are on located on a GitHub repository at: ubuntu-cloud-docs and you’ll need a GitHub account to make contributions. It is a good idea to fork this repository into your own account before you start, otherwise GitHub will anyway prompt you to do so when you attempt your first change.

The docs are:

We are always looking for ways to improve our docs, so we appreciate your contributions!

Minor changes

If you’ve found a problem that can be fixed with a small change, you can use the Edit this page on GitHub link at the bottom of the relevant page to edit it directly on GitHub. When you are done with your edits, select Commit changes… on the top right. This will help you create a new branch and start a pull request (PR). Use Propose changes to submit the PR. We will review it and merge the changes.

Suggestions and questions

Use the Give feedback button at the top of any page to create a GitHub issue for any suggestions or questions that you might have.

New content

While contributing new content, it is easier to work with the docs on your local machine. You can submit a PR after all the checks have passed and things looks satisfactory. You’ll need make and python3 installed on your system.

Download and install the docs

If you are working with these docs for the first time, you’ll need to create a fork of the ubuntu-cloud-docs repository on your GitHub account and then clone that fork to your local machine. Once cloned, go into the ubuntu-cloud-docs directory and run:

make install

This creates a virtual environment and installs all the required dependencies. You only have to do this step once, and can skip it the next time you want to contribute.

Build and serve the docs

Use the make run command to build and serve the docs at http://127.0.0.1:8000 or equivalently at http://localhost:8000. This gives you a live preview of the changes that you make (and save), without the need for a rebuild:

PROJECT=oci make run

Setting the PROJECT parameter to oci ensures that the documentation set for Ubuntu on OCI Registries gets built. This parameter is needed to distinguish between the different documentation sets present in the repository.

Perform checks and submit PR

Before opening a PR, run the following checks and also ensure that the documentation builds without any warnings (warnings are treated as errors in the publishing process):

PROJECT=oci make spelling
PROJECT=oci make linkcheck
PROJECT=oci make woke

If you need to add new words to the allowed list of words, include them in .custom_wordlist.txt.

Once all the edits are done, commit the changes and push it to your fork. From the GitHub GUI of your fork, select the commit and open a PR for it.