docs: restructure and apply diataxis to OCI docs

.gitignore

@@ -10,3 +10,4 @@ _build
 .DS_Store
 __pycache__
 .idea/
+oci/_external/*.rst

custom_conf.py

@@ -161,9 +161,9 @@
 # NOTE: Remove this variable to disable the MyST parser extensions.
 custom_myst_extensions = []
 
-# Add custom Sphinx extensions as needed. 
+# Add custom Sphinx extensions as needed.
 # This array contains recommended extensions that should be used.
-# NOTE: The following extensions are handled automatically and do 
+# NOTE: The following extensions are handled automatically and do
 # not need to be added here: myst_parser, sphinx_copybutton, sphinx_design,
 # sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph
 custom_extensions = [
@@ -202,7 +202,7 @@
     "google": {},
     "ibm": {},
     "oracle": {},
-    "oci": {}
+    "oci": {},
 }
 
 intersphinx_mapping = {

oci/conf.py

@@ -1,51 +1,59 @@
+import pathlib
+import urllib.request
+
 # Configuration file for the Sphinx documentation builder.
-project = 'Ubuntu on OCI Registries'
+project = "Ubuntu on OCI Container Registries"
 
 # The title you want to display for the documentation in the sidebar.
 # You might want to include a version number here.
 # To not display any title, set this option to an empty string.
-html_title = project + ' documentation'
+html_title = project + " documentation"
 
-# Some settings in the html_context dictionary have to be repeated 
+# Some settings in the html_context dictionary have to be repeated
 # in the sub projects for correct functioning (don't remove them)
 html_context = {
-
     # Add your product tag (the orange part of your logo, will be used in the
     # header) to ".sphinx/_static" and change the path here (start with "_static")
     # (default is the circle of friends)
-    'product_tag': '_static/tag.png',
-
+    "product_tag": "_static/tag.png",
     # Change to the discourse instance you want to be able to link to
     # using the :discourse: metadata at the top of a file
     # (use an empty value if you don't want to link)
-    'discourse': 'https://discourse.ubuntu.com/c/public-cloud/',
-
+    "discourse": "https://discourse.ubuntu.com/c/public-cloud/",
     # Change to the Mattermost channel you want to link to
     # (use an empty value if you don't want to link)
-    'mattermost': 'https://chat.canonical.com/canonical/channels/public-cloud-eng',
-
+    "mattermost": "https://chat.canonical.com/canonical/channels/public-cloud-eng",
     # Change to the GitHub URL for your project
-    'github_url': 'https://github.com/canonical/ubuntu-cloud-docs',
-
+    "github_url": "https://github.com/canonical/ubuntu-cloud-docs",
     # Change to the branch for this version of the documentation
-    'github_version': 'main',
-
+    "github_version": "main",
     # Change to the folder that contains the documentation
     # (usually "/" or "/docs/")
-    'github_folder': '/oci/',
-
+    "github_folder": "/oci/",
     # Change to an empty value if your GitHub repo doesn't have issues enabled.
     # This will disable the feedback button and the issue link in the footer.
-    'github_issues': 'enabled',
-
-    # Change to the folder that contains the documentation 
+    "github_issues": "enabled",
+    # Change to the folder that contains the documentation
     # (usually "/" or "/docs/")
-    "conf_py_path": '/oci/',
-
+    "conf_py_path": "/oci/",
     # Controls the existence of Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
     # You can override the default setting on a page-by-page basis by specifying
     # it as file-wide metadata at the top of the file, see
     # https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
-    'sequential_nav': "both"
+    "sequential_nav": "both",
+}
+
+# These docs reuse some content from other docs
+pro_client_docs = {
+    "enable-pro-services.rst": "https://raw.githubusercontent.com/canonical/ubuntu-pro-client/docs/docs/howtoguides/enable_in_dockerfile.rst",
+    "create-fips-container-image.rst": "https://raw.githubusercontent.com/canonical/ubuntu-pro-client/docs/docs/tutorials/create_a_fips_docker_image.rst",
 }
+common_docs_path = pathlib.Path(__file__).parent / "_external"
+exclude_patterns = ["_external"]
+for page in pro_client_docs:
+    urllib.request.urlretrieve(
+        pro_client_docs[page],
+        common_docs_path / page,
+    )
+    # exclude_patterns.append(str(common_docs_path / page))

oci/index.rst

@@ -1,82 +1,64 @@
-Ubuntu on OCI Registries
-========================
+Ubuntu on OCI container registries
+==================================
 
-The Open Container Initiative (OCI) establishes standards for constructing container 
-images that can be reliably installed across a variety of compliant host environments.
+**Ubuntu is one of the world's most popular container images.** A minimalistic Ubuntu image that offers the same security, versatility, and update cadence as other Ubuntu offerings. A developer favourite in container registries such as Docker Hub, with up to 30,000 pulls per week.
 
-Ubuntu’s `LTS Docker Image Portfolio <https://ubuntu.com/security/docker-images>`_ 
-provides OCI-compliant images that receive stable security updates and predictable 
-software updates, thus ensuring consistency in both maintenance schedule and operational 
-interfaces for the underlying software your software builds on.
+**Available in all major OCI container registries,** such as Microsoft's ACR, Amazon's ECR, and of course, Docker Hub, as an official image from a verified publisher - Canonical. 
 
-Ubuntu OCI tarball is a minimal rootfs tarball ready for use to build OCI/Docker 
-container base images. It is similar to `Ubuntu Base <https://wiki.ubuntu.com/Base>`_ 
-but already contains the modifications needed to make the rootfs suitable for 
-building OCI/Docker container images. It is available for the amd64, armhf, arm64, 
-powerpc and ppc64el architectures. The rootfs tarballs are published under 
-`OCI partner images <https://partner-images.canonical.com/oci/>`_. 
+**A base container for trusted application images.** Container image provenance is a key aspect of any supply chain. The Ubuntu container image offers the ideal starting point for your application images, both in utility and trustworthiness.
 
-Canonical publishes official Docker images to Docker Hub based on OCI images that are 
-built from the Ubuntu OCI rootfs tarballs. Images are also published to AWS ECR 
-(Elastic Container Registry) gallery (in `ubuntu <https://gallery.ecr.aws/ubuntu/ubuntu>`_
-and `lts <https://gallery.ecr.aws/lts/ubuntu>`_ namespaces), ACR (Azure Container Registry),
-OCIR (Oracle Container Infrastructure Registry), and there are plans to publish to more
-registries in the future.
+**Compatible with multiple platforms and available in different flavours.** The Ubuntu container image is published as a multi-arch OCI (Open Container Initiative) image that is available for ``amd64``, ``arm``, ``arm64``, ``ppc64le`` and ``s390x``. Moreover, Ubuntu Pro is also available for containers, which means hardened and security-enhanced versions of the public Ubuntu container image are also available.
 
 
-----------
+.. toctree::
+   :maxdepth: 1
+   :hidden:
 
-.. _building_ubuntu_pro_oci_images:
+   oci-tutorials/index
+   oci-how-to/index
+   oci-reference/index
+   oci-explanation/index
 
-Building Ubuntu Pro OCI images
-------------------------------
 
-Similar to the `Ubuntu Pro images in public clouds <https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/explanations/what_are_ubuntu_pro_cloud_instances/>`_, one can build an Ubuntu Pro OCI image to leverage services like ESM (Extended Security Maintenance) and FIPS.
+.. grid:: 1 1 2 2
 
-The easiest way to build an Ubuntu Pro container image is to make use of existing container management tools (like Docker) and enable the Pro services on top of an existing Ubuntu container image (e.g. `ubuntu:focal <https://hub.docker.com/layers/library/ubuntu/focal/images/sha256-b39db7fc56971aac21dee02187e898db759c4f26b9b27b1d80b6ad32ff330c76?context=explore>`_).
+   .. grid-item-card:: :ref:`Tutorials <oci-tutorials>`
 
-.. note::
-   It is highly recommended that Ubuntu Pro container images should be built on hosts that are already covered by an Ubuntu Pro subscription.
+      **Get started** - become familiar with the Ubuntu container image and its
+      common usage.
 
-This process is described in detail in the `pro client documentation <https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/enable_in_dockerfile/>`_. The resulting Ubuntu Pro container image can then be loaded into your local Docker daemon (by using ``--load`` when running ``docker build``) and can be deployed/published normally as any other container image.
+   .. grid-item-card:: :ref:`How-to guides <oci-how-to>`
 
+      **Step-by-step guides** - learn how to use the Ubuntu container image to
+      achieve a goal, like :ref:`deploying a Pro container
+      image to a Pro Kubernetes cluster
+      <how-to-deploy-pro-container-on-pro-cluster>`.
 
-----------
+.. grid:: 1 1 2 2
+   :padding: 0
+   :reverse:
 
-How-to guides
--------------
+   .. grid-item-card:: :ref:`Reference <oci-reference>`
 
-Instructions for deploying Ubuntu Pro containers on Kubernetes and for creating a 'chiselled' Ubuntu base image are linked below:
+      **Technical information** - understand the Ubuntu container images'
+      design and where you can get them from.
 
-* :doc:`Deploy Pro containers on K8s <./oci-how-to/deploy-pro-container-on-pro-kubernetes-cluster>`
-* :doc:`Create a chiselled image <./oci-how-to/create-chiselled-ubuntu-image>`
+   .. grid-item-card:: :ref:`Explanation <oci-explanation>`
 
+      **Discussion and clarification** - dive a bit deeper into what Ubuntu and
+      Ubuntu Pro container images are.
 
----------
 
 Project and community
----------------------
-
-Ubuntu on OCI registries is a member of the Ubuntu family and the project warmly welcomes 
-community projects, contributions, suggestions, fixes and constructive feedback.
-
-* `Get support`_
-* `Join our online chat`_
-* `Discuss on IRC`_
-* :doc:`oci-how-to/contribute-to-these-docs`
-* `Code of conduct`_
-
-.. toctree::
-   :hidden:
-   :maxdepth: 2
-
-   Deploy Pro containers on K8s <oci-how-to/deploy-pro-container-on-pro-kubernetes-cluster>
-   Create a chiselled image <oci-how-to/create-chiselled-ubuntu-image>
-   oci-how-to/contribute-to-these-docs
-
-
-.. _Get support: https://ubuntu.com/cloud/public-cloud
-.. _Join our online chat: https://discourse.ubuntu.com/c/public-cloud/176
-.. _`Discuss on IRC`: https://web.libera.chat/#ubuntu-cloud
-.. _Code of conduct: https://ubuntu.com/community/ethos/code-of-conduct
-
+=====================
+
+This project is a member of the Ubuntu family and it warmly welcomes community
+projects, contributions, suggestions, fixes, and constructive feedback.
+
+* `Get support <https://ubuntu.com/cloud/public-cloud>`_
+* `Join our online chat <https://discourse.ubuntu.com/c/public-cloud/176>`_
+* `Discuss on IRC <https://web.libera.chat/#ubuntu-cloud>`_
+* `Ubuntu Docker Images on Launchpad <https://launchpad.net/ubuntu-docker-images>`_
+* `Ubuntu Code of Conduct <https://ubuntu.com/community/code-of-conduct>`_
+* `Canonical contributor license agreement
+  <https://ubuntu.com/legal/contributors>`_

oci/links.txt

@@ -0,0 +1,2 @@
+.. _Pro: https://ubuntu.com/pro
+.. _Ubuntu One: https://login.ubuntu.com/

oci/oci-explanation/index.rst

@@ -0,0 +1,14 @@
+.. _oci-explanation:
+
+***********
+Explanation
+***********
+
+This section of the documentation covers the definitions of the Ubuntu and
+Ubuntu Pro container images.
+
+.. toctree::
+   :maxdepth: 1
+
+   ubuntu-oci-container
+   ubuntu-pro-oci-container

oci/oci-explanation/ubuntu-oci-container.rst

@@ -0,0 +1,22 @@
+.. _ubuntu-oci-container-images:
+
+Ubuntu OCI container images
+===========================
+
+The Open Container Initiative (OCI) establishes standards for constructing container 
+images that can be reliably installed across a variety of compliant host environments.
+
+Ubuntu’s `LTS Docker Image Portfolio <https://ubuntu.com/security/docker-images>`_ 
+provides OCI-compliant images that receive stable security updates and predictable 
+software updates, thus ensuring consistency in both maintenance schedule and operational 
+interfaces for the underlying software your software builds on.
+
+Moreover, `Ubuntu-based containers <https://ubuntu.com/containers>`_ (like
+chiselled container images) all leverage the Ubuntu container image as their
+starting point, and thus also profit from its support and security commitments.
+
+The Ubuntu container image is built from a minimal rootfs tarball. This tarball
+is similar to `Ubuntu Base <https://wiki.ubuntu.com/Base>`_ 
+but it already contains the modifications needed to make the rootfs suitable for 
+building OCI/Docker container images. The Ubuntu OCI rootfs tarballs are published
+in `OCI partner images <https://partner-images.canonical.com/oci/>`_. 

oci/oci-explanation/ubuntu-pro-oci-container.rst

@@ -0,0 +1,17 @@
+.. _ubuntu-pro-oci-container-images:
+
+Ubuntu Pro OCI container images
+===============================
+
+
+Similar to the `Ubuntu Pro images in public clouds
+<https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/explanations/what_are_ubuntu_pro_cloud_instances/>`_, one can build an Ubuntu Pro container image to leverage services like ESM
+(Extended Security Maintenance) and FIPS.
+
+The easiest way to build an Ubuntu Pro container image is to make use of existing container management tools (like Docker) and enable the Pro services on top of an existing Ubuntu container image (e.g. `ubuntu:focal <https://hub.docker.com/_/ubuntu/tags?page=&page_size=&ordering=&name=focal>`_).
+
+.. note::
+   Ubuntu Pro container images should be run on hosts that are already covered by an Ubuntu Pro subscription.
+   Please consult the `Ubuntu Pro service description <https://ubuntu.com/legal/ubuntu-pro>`_ for more details.
+
+This process is described in detail in :ref:`this How-to guide <oci-how-to-enable-pro-services>`. The resulting Ubuntu Pro container image can then be loaded into your local Docker daemon and/or can be deployed normally as any other container image.

oci/oci-how-to/contribute-to-these-docs.rst

@@ -1,5 +1,5 @@
 Contribute to these docs
-========================
+************************
 
 .. include:: ../../reuse/contribute-to-docs.txt
    :start-after: Start: How to contribute
@@ -13,7 +13,7 @@ Contribute to these docs
 
 	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.
+Setting the `PROJECT` parameter to ``oci`` ensures that the documentation set for `Ubuntu on Container Registries` gets built. This parameter is needed to distinguish between the different documentation sets present in the repository.
 
 .. include:: ../../reuse/contribute-to-docs.txt
    :start-after: Start: How to contribute (continued)

oci/oci-how-to/create-chiselled-ubuntu-image.rst

@@ -1,7 +1,7 @@
 Create a chiselled Ubuntu base image for C/C++, Go and Rust applications
-========================================================================
+************************************************************************
 
-This guide will provide step-by-step instructions on how  to create your own chiselled Ubuntu container image to run a compiled application.
+This guide will provide step-by-step instructions on how to create your own chiselled Ubuntu container image to run a compiled application.
 
 - Chiselled Ubuntu are appliance-type container images combining both the advantages of distroless and Ubuntu to create smaller, more secure containers, without loosing the value add of a stable Linux distribution.
 - The reduced size of the containers reduces the overall attack surface. Combined with the support and content quality from the Ubuntu distribution, chiselled Ubuntu is a significant security improvement.

oci/oci-how-to/deploy-pro-container-on-pro-kubernetes-cluster.rst

@@ -1,5 +1,7 @@
+.. _how-to-deploy-pro-container-on-pro-cluster:
+
 Deploy Ubuntu Pro containers on Kubernetes
-==========================================
+******************************************
 
 You can easily deploy your Ubuntu Pro container images on Kubernetes clusters, provided
 that said clusters are composed of Ubuntu Pro nodes. Read more on the

oci/oci-how-to/enable-pro-services.rst

@@ -0,0 +1,3 @@
+.. _oci-how-to-enable-pro-services:
+
+.. include:: /_external/enable-pro-services.rst

oci/oci-how-to/getting-started.rst

@@ -0,0 +1,44 @@
+Getting Started
+***************
+
+This is where to find the Ubuntu container images:
+
+.. tabs::
+
+	.. tab:: Docker Hub
+
+         .. code-block:: bash
+
+            docker pull ubuntu:latest
+            
+
+	.. tab:: Amazon ECR
+
+         .. code-block:: bash
+            
+            docker pull public.ecr.aws/ubuntu/ubuntu:latest
+
+	.. tab:: Microsoft ACR
+
+         .. code-block:: bash
+            
+            docker pull ubuntu.azurecr.io/ubuntu:latest
+
+	.. tab:: IronBank
+
+         .. note::
+            Please note that these Ubuntu container images may have special terms of use and fall under Ubuntu Pro. Please reach out if you would like to use the Ubuntu container images from IronBank.
+
+
+
+
+Refresh rate
+------------
+
+The Ubuntu base container images can be automatically updated multiple times a
+day, depending on whether there have been upstream changes in the Ubuntu archives
+affecting the packages that constitute the container image.
+
+**Exception**: the only exception is the official Ubuntu image in Docker Hub which,
+due to the Docker's policies, cannot be submitted too regularly, and thus are
+only updated every two weeks.