Merge pull request #111 from k-dimple/main

Reorganise AWS how-tos and include 'How to contribute to these docs'

.wordlist.txt

@@ -205,3 +205,7 @@ virtualised
 CNCF
 AgentBaker
 sku
+Diátaxis
+reStructuredText
+localhost
+HTML

aws/aws-how-to/contributions/contribute-to-these-docs.rst

@@ -0,0 +1,39 @@
+Contribute to these docs
+========================
+
+.. include:: ../../../reuse/contribute-to-docs.txt
+   :start-after: Start: How to contribute
+   :end-before: End: How to contribute
+
+.. code::
+
+	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.
+
+If you don't want to preview the changes continuously and only wish to build the docs once (e.g., to have a local copy on your machine), then run ``PROJECT=aws make html``. This will create the AWS related HTML pages in _build/aws. You can preview the site by opening ``index.html`` on your web browser. 
+
+
+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):
+
+.. code::
+
+	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 ``.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.
+
+.. _`ubuntu-cloud-docs`: https://github.com/canonical/ubuntu-cloud-docs
+.. _`Diátaxis`: https://diataxis.fr/
+.. _`reStructuredText`: https://docutils.sourceforge.io/rst.html
+.. _`Canonical style guide`: https://docs.ubuntu.com/styleguide/en
+.. _`Sphinx`: https://www.sphinx-doc.org/en/master/
+.. _`Read the Docs`: https://readthedocs.com
+
+

aws/aws-how-to/contributions/index.rst

@@ -0,0 +1,9 @@
+Contributions
+=============
+
+
+.. toctree::
+   :maxdepth: 1
+
+   contribute-to-these-docs
+

aws/aws-how-to/index.rst

@@ -1,39 +1,35 @@
 How-to guides
 =============
 
-If you want to find the right Ubuntu image, upgrade from Ubuntu 20.04 to 22.04, create CloudFormation templates, automatically update your Ubuntu instances, or just launch an Ubuntu desktop on EC2, refer to these guides:
+Launching and using Ubuntu instances:
 
-* :doc:`./find-ubuntu-images`
-* :doc:`./upgrade-from-focal-to-jammy`
-* :doc:`./build-cloudformation-templates`
-* :doc:`./automatically-update-ubuntu-instances` 
-* :doc:`./launch-ubuntu-desktop`
+* :doc:`instances/find-ubuntu-images`
+* :doc:`instances/build-pro-ami-using-packer`
+* :doc:`instances/build-cloudformation-templates`
+* :doc:`instances/launch-ubuntu-desktop`
+* :doc:`instances/automatically-update-ubuntu-instances` 
+* :doc:`instances/upgrade-from-focal-to-jammy`
 
-Ubuntu Pro related user guides: 
+Using Kubernetes: 
 
-* :doc:`./build-pro-ami-using-packer`
-* :doc:`./deploy-ubuntu-pro-cluster`
-* :doc:`./deploy-charmed-kubernetes-on-ubuntu-pro`
+* :doc:`kubernetes/deploy-ubuntu-pro-cluster`
+* :doc:`kubernetes/enable-gpus-on-eks`
+* :doc:`kubernetes/deploy-charmed-kubernetes-on-ubuntu-pro`
 
-Finally, if you want to use UEFI Secure Boot or enable GPUs on EKS worker nodes, use:
+Security:
 
-* :doc:`./use-secureboot-and-vtpm` 
-* :doc:`./enable-gpus-on-eks`
+* :doc:`security/use-secureboot-and-vtpm` 
 
+Contributions:
+
+* :doc:`contributions/contribute-to-these-docs`
 
 .. toctree::
    :hidden:
    :maxdepth: 1
 
-   find-ubuntu-images   
-   upgrade-from-focal-to-jammy
-   build-cloudformation-templates
-   automatically-update-ubuntu-instances
-   launch-ubuntu-desktop
-
-   build-pro-ami-using-packer
-   deploy-ubuntu-pro-cluster  
-   deploy-charmed-kubernetes-on-ubuntu-pro
-
-   use-secureboot-and-vtpm   
-   enable-gpus-on-eks
+   instances/index    
+   kubernetes/index
+   security/index   
+   contributions/index
+

aws/aws-how-to/instances/index.rst

@@ -0,0 +1,12 @@
+EC2 instances
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   find-ubuntu-images   
+   build-pro-ami-using-packer
+   build-cloudformation-templates
+   launch-ubuntu-desktop
+   automatically-update-ubuntu-instances
+   upgrade-from-focal-to-jammy

aws/aws-how-to/deploy-ubuntu-pro-cluster.rst → aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst

@@ -26,7 +26,7 @@ The steps needed for deploying the cluster depend on whether you need to enable
 
 .. tabs::
 
-    .. tab:: Without FIPS
+    .. group-tab:: Without FIPS
 
         When FIPS is not enabled, you can use one of the existing Ubuntu EKS AMIs and
         customise it using cloud-init's `ubuntu-advantage module <https://cloudinit.readthedocs.io/en/latest/reference/modules.html#ubuntu-advantage>`_ during deployment.
@@ -61,7 +61,7 @@ The steps needed for deploying the cluster depend on whether you need to enable
         Cloud-init will use this user-data to enable ESM on the cluster nodes and bootstrap the AWS EKS cluster.
 
 
-    .. tab:: With FIPS
+    .. group-tab:: With FIPS
 
         When enabling FIPS, a reboot of the underlying node is required. If this reboot is done after the cluster is created, in rare cases, it might result in the node being flagged as defective (`troubleshooting options <https://docs.aws.amazon.com/eks/latest/userguide/troubleshooting.html>`_). For this reason, the most reliable way to deploy an Ubuntu Pro EKS cluster is to build a custom Ubuntu Pro AMI (with `Packer <https://www.packer.io/>`_) and use it during cluster creation until this `issue <https://bugs.launchpad.net/cloud-images/+bug/2017782>`_ is resolved.
 
@@ -184,7 +184,7 @@ Add the following content to your file
 
 .. tabs::
 
-	.. tab:: Without FIPS
+	.. group-tab:: Without FIPS
 
          .. code-block:: yaml
 
@@ -198,7 +198,7 @@ Add the following content to your file
          This config file will allow you to create an EKS cluster using the launch template
          from above, with two nodes. 
 
-	.. tab:: With FIPS
+	.. group-tab:: With FIPS
 
          .. code-block:: yaml
 

aws/aws-how-to/kubernetes/index.rst

@@ -0,0 +1,9 @@
+EKS and Charmed Kubernetes
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   deploy-ubuntu-pro-cluster  
+   enable-gpus-on-eks
+   deploy-charmed-kubernetes-on-ubuntu-pro

aws/aws-how-to/security/index.rst

@@ -0,0 +1,7 @@
+Security features
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   use-secureboot-and-vtpm

aws/index.rst

@@ -43,11 +43,12 @@ suggestions, fixes and constructive feedback.
 * `Get support`_
 * `Join our online chat`_
 * `Talk to us about Ubuntu on AWS`_
+* :doc:`aws-how-to/contributions/contribute-to-these-docs`
 
 
 .. toctree::
    :hidden:
-   :maxdepth: 2
+   :maxdepth: 1
 
    aws-how-to/index
    aws-explanation/index

reuse/common-intro.txt

@@ -49,3 +49,5 @@ End: Daily vs release images
 
 ==============================================================
 
+
+

reuse/contribute-to-docs.txt

@@ -0,0 +1,52 @@
+==============================================================
+
+Start: How to contribute
+
+These docs are on located on a GitHub repository at: `ubuntu-cloud-docs`_ and you'll need a GitHub account to make contributions. The docs are:
+
+	* structured using the `Diátaxis`_ approach,
+	* written in `reStructuredText`_ as per the `Canonical style guide`_,
+	* built with `Sphinx`_ and
+	* hosted on `Read the Docs`_.
+
+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 pencil icon at the top of the relevant page to edit it on GitHub. When you are done with your edits, select :guilabel:`Commit changes...` on the top right. This will help you create a new branch and start a pull request (PR). Use :guilabel:`Propose changes` to submit the PR. We will review it and merge the changes.
+
+
+Suggestions and questions
+-------------------------
+
+Use the :guilabel:`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.
+
+Download and install the docs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are working with these docs for the first time, you'll need to fork and clone the `ubuntu-cloud-docs`_ repository to your local machine. Once cloned, go into the ubuntu-cloud-docs directory and run:
+
+.. code::
+
+	make install
+
+This creates a virtual environment and installs all the dependencies specified in ``.sphinx/requirements.txt``. You only have to do this once (unless you run a ``make clean`` sometime), and can skip this step the next time you want to contribute.
+
+
+Build and serve the docs
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the ``make run`` command to build and serve the docs at `127.0.0.1:8000 <http://127.0.0.1:8000>`_ or equivalently at `localhost:8000 <http://localhost:8000>`_. This gives you a live preview of the changes that you make (and save), without the need for a rebuild:
+
+
+End: How to contribute
+
+==============================================================
+