Contribute to these docs¶

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

This documentation set is:

structured using the Diátaxis approach
written in reStructuredText as per the Canonical style guide
built with Sphinx
hosted on Read the Docs

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

Minor changes¶

If you find a problem that you can fix and it’s 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¶

When adding new content, it’s easier to work with the documentation on your local machine. For this, you’ll need make and python3 installed on your system. Once you’ve made your changes, ensure all checks have passed and everything looks satisfactory before submitting a pull request (PR).

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=oracle make run

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

Create content¶

Choose the appropriate folder for your content. The folders within each project are mapped to the Diátaxis categories of tutorial, how-to guides, explanation and reference. If required, the categories can have subcategories as well, as shown in the tree structure below. Also, each folder includes an index.rst file, which acts as a landing page for the folder.

project/
├── tutorial
├── how-to-guides/
│   ├── subcategory-one/
│   │   ├── index.rst
│   │   ├── page-one.rst
│   │   ├── page-two.rst
│   │   └── page-three.rst
│   └── subcategory-two/
│   |   ├── index.rst
│   |   ├── page-one.rst
│   |   ├── page-two.rst
│   |   └── page-three.rst
|   └── index.rst
├── explanation
├── reference
└── index.rst

If your required category or subcategory is absent, create them using the instructions given below. Then add your content by creating a new page.

Create new categories (optional)¶

You can create new categories by following these steps:

Create a new folder in your documentation directory.
Create a new index.rst file within your new folder.
Add the title of your new category to the first line of the index.rst file. Underline it using equal signs (=) that match the length of your title. For more information on titles and headings, read the reStructuredText style guide.
In the index.rst file, add content introducing the category, its purpose, and other relevant links.
In your index.rst file, add a toctree that specifies the file names of pages and the index files of the subcategories within your newly created category. The toctree should resemble the following structure:

.. toctree::
   :maxdepth: 2

   subcategory-one/index
   Subcategory two <subcategory-two/index>
   page-one-file-name

For more information, read the Sphinx documentation on toctree.

Update the project’s main index.rst file by adding your new category to its toctree.

Create new subcategories (optional)¶

You can create new subcategories by following these steps:

Go to the parent category and create a new folder for your subcategory within it.
Create an index.rst file within the subcategory folder.
Enter the title of your new subcategory on the first line of the index.rst file. Underline it using equal signs (=) that match the length of your title. For more information on titles and headings, read the reStructuredText style guide.
In the index.rst file, add content introducing the subcategory, its purpose, and other relevant links.
In your index.rst file, add a toctree that includes the file names or titles of pages within your new subcategory. The toctree should resemble the following structure:

.. toctree::
   :maxdepth: 1

   page-one-file-name
   Page Two Title <page-two-file-name>

Update the index.rst file of the parent category by adding a reference to the newly created subcategory in its toctree.

Create new pages¶

You can create new pages by following these steps:

Create a new file within a category or subcategory.
Add a title to the first line of the file. Underline it using equal signs (=) that match the length of your title. For more information on titles and headings, read the reStructuredText style guide.
Add content to the new file using reStructuredText and following the Canonical style guide.
Update the category or subcategory’s index.rst file by adding the file name or your preferred title to the toctree. For more information, read the Sphinx documentation on toctree.

Perform checks and submit a 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=oracle make spelling
PROJECT=oracle make linkcheck
PROJECT=oracle 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.