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:
structured using the Diátaxis approach,
built with Sphinx and
hosted on Read the Docs.
We are always looking for ways to improve our docs, so we appreciate your contributions!
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.
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
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:
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=aws make run
Setting the PROJECT parameter to aws
ensures that the documentation set for Ubuntu on AWS 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=aws make spelling
PROJECT=aws make linkcheck
PROJECT=aws 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.