New tutorial

doc/rtd/development/style_docs.rst

@@ -90,9 +90,9 @@ to text output, you can use code blocks. For diagrams, we recommend the use of
 Code blocks
 -----------
 
-Our documentation uses the Sphinx extension "sphinx-copybutton", which creates
-a small button on the right-hand side of code blocks for users to copy the
-code snippets we provide.
+Our documentation uses the Sphinx extension ``sphinx-copybutton``, which
+creates a small button on the right-hand side of code blocks for users to copy
+the code snippets we provide.
 
 The copied code will strip out the prompt symbol (``$``) so that users can
 paste commands directly into their terminal. For user convenience, please

doc/rtd/howto/index.rst

@@ -18,6 +18,7 @@ How do I...?
 .. toctree::
    :maxdepth: 1
 
+   Launch cloud-init with... <launching.rst>
    Run cloud-init locally before deploying <run_cloud_init_locally.rst>
    Re-run cloud-init <rerun_cloud_init.rst>
    Change how often a module runs <module_run_frequency.rst>

doc/rtd/howto/launching.rst

@@ -0,0 +1,20 @@
+.. _launching:
+
+Launching instances with cloud-init
+***********************************
+
+Due to differences across platforms, initializing and launching instances with
+cloud-init can vary. Here we present instructions for various platforms, or
+links to instructions where platforms have provided their preferred methods for
+using cloud-init.
+
+* :ref:`With WSL <launching>`
+
+  In this guide you will use a cloud-init user data script to customize a WSL
+  instance.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   WSL <wsl.rst>

doc/rtd/howto/run_cloud_init_locally.rst

@@ -73,7 +73,7 @@ Download an Ubuntu image to run:
 .. note::
    This example uses emulated CPU instructions on non-x86 hosts, so it may be
    slow. To make it faster on non-x86 architectures, one can change the image
-   type and :spelling:ignore:`qemu-system-<arch>` command name to match the
+   type and ``qemu-system-<arch>`` command name to match the
    architecture of your host machine.
 
 Boot the image with the ISO attached

doc/rtd/tutorial/wsl.rst → doc/rtd/howto/wsl.rst

@@ -1,26 +1,18 @@
 .. _tutorial_wsl:
 
-WSL Tutorial
-************
+Using WSL with cloud-init
+*************************
 
-In this tutorial, we will customize a Windows Subsystem for Linux (WSL)
+In this guide, we will customize a `Windows Subsystem for Linux`_ (WSL)
 instance using cloud-init on Ubuntu.
 
-How to use this tutorial
-========================
-
-In this tutorial, the commands in each code block can be copied and pasted
-directly into a ``PowerShell`` Window . Omit the prompt before each
-command, or use the "copy code" button on the right-hand side of the block,
-which will copy the command for you without the prompt.
-
 Prerequisites
 =============
 
-This tutorial assumes you are running within a ``Windows 11`` or ``Windows
+This guide assumes you are running within a ``Windows 11`` or ``Windows
 Server 2022`` environment. If ``wsl`` is already installed, you must be
 running version 2. You can check your version of ``wsl`` by running the
-following command:
+following command in your terminal:
 
 .. code-block:: doscon
 
@@ -38,9 +30,8 @@ Example output:
     DXCore version: 10.0.25131.1002-220531-1700.rs-onecore-base2-hyp
     Windows version: 10.0.20348.2402
 
-If running this tutorial within a virtualized
-environment (`including in the cloud`_), ensure that
-`nested virtualization`_ is enabled.
+If you follow this guide while using a virtualized environment
+(`including in the cloud`_), ensure that `nested virtualization`_ is enabled.
 
 Install WSL
 ===========
@@ -66,8 +57,8 @@ Example output:
 
 Reboot the system when prompted.
 
-Create our user data
-====================
+Create some user data
+=====================
 
 User data is the primary way for a user to customize a cloud-init instance.
 Open Notepad and paste the following:
@@ -91,7 +82,7 @@ not as a ``.txt`` file.
 .. note::
     We are creating user data that is tied to the instance we just created,
     but by changing the filename, we can create user data that applies to
-    multiple or all WSL instances. See
+    multiple (or all) WSL instances. See
     :ref:`WSL Datasource reference page<wsl_user_data_configuration>` for
     more information.
 
@@ -167,7 +158,7 @@ Download the Ubuntu 24.04 WSL image.
 
     PS> Invoke-WebRequest -Uri https://cloud-images.ubuntu.com/wsl/noble/current/ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz -OutFile wsl-images\ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz
 
-Import the image into WSL storing it in the ``wsl-images`` directory.
+Import the image into WSL, storing it in the ``wsl-images`` directory.
 
 .. code-block:: doscon
 
@@ -186,8 +177,8 @@ Start the Ubuntu WSL instance
 
     PS> wsl --distribution Ubuntu-24.04
 
-Setup the Ubuntu WSL instance
-=============================
+Set up the Ubuntu WSL instance
+==============================
 
 The Ubuntu WSL instance will start, and you may be prompted for a username
 and password.
@@ -224,7 +215,7 @@ screen similar to the following:
     /root/.hushlogin file.
     root@machine:/mnt/c/Users/me#
 
-You should now be in a shell inside the WSL instance.
+This indicates you are now in a shell inside the WSL instance.
 
 Verify that ``cloud-init`` ran successfully
 -------------------------------------------
@@ -305,7 +296,7 @@ successfully!
 What's next?
 ============
 
-In this tutorial, we used the :ref:`Write Files module <mod_cc_write_files>` to
+In this guide, we used the :ref:`Write Files module <mod_cc_write_files>` to
 write a file to our WSL instance. The full list of modules available can be
 found in our :ref:`modules documentation<modules>`.
 Each module contains examples of how to use it.
@@ -316,7 +307,7 @@ examples of more common use cases.
 Cloud-init's WSL reference documentation can be found on the
 :ref:`WSL Datasource reference page<datasource_wsl>`.
 
-
+.. _Windows Subsystem for Linux: https://learn.microsoft.com/en-us/windows/wsl/
 .. _including in the cloud: https://techcommunity.microsoft.com/t5/itops-talk-blog/how-to-setup-nested-virtualization-for-azure-vm-vhd/ba-p/1115338
 .. _nested virtualization: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/user-guide/nested-virtualization
 .. _Ubuntu 24.04: https://apps.microsoft.com/detail/9nz3klhxdjp5

doc/rtd/index.rst

@@ -87,8 +87,9 @@ projects, contributions, suggestions, fixes and constructive feedback.
 
    tutorial/index
    howto/index
-   explanation/index
    reference/index
+   explanation/index
+
 
 .. toctree::
    :caption: Development

doc/rtd/spelling_word_list.txt

@@ -2,7 +2,6 @@ akamai
 alibaba
 almalinux
 ami
-analyze
 ansible
 apk
 apport
@@ -13,13 +12,12 @@ artifacts
 authkeys
 autoinstaller
 autospecced
-avaliable
+available
 aways
 aws
 backend
 backends
 baseurl
-behavior
 bigstep
 boolean
 bootcmd
@@ -33,21 +31,22 @@ centos
 chown
 chrony
 cleanup
-cloudinit
+cloud-init
 cloudlinux
 cloudplatform
 conf
 config
 configdrive
 configs
-copybutton
+copy-button
 cpu
 csr
 datasource
 datasources
 deadbeef
 debconf
 debian
+dev
 devops
 dhcp
 dicts
@@ -83,11 +82,8 @@ execve
 exoscale
 fabio
 faillog
-favor
-favorite
 fips
 firstboot
-flavors
 flexibile
 fqdn
 freebsd
@@ -102,7 +98,6 @@ growpart
 gz
 hacktoberfest
 hetzner
-honored
 hostname
 hpc
 ids
@@ -120,7 +115,6 @@ kenv
 keygen
 keytypes
 kyler
-labeled
 lastlog
 libvirt
 linux
@@ -149,7 +143,6 @@ netplan
 networkd
 nistp
 nocloud
-nonexistent
 ntp
 ntpd
 ntpdate
@@ -195,11 +188,8 @@ rc
 rd
 readinessprobes
 redhat
-referesh
 regex
-renderes
 repodata
-repositoy
 resizefs
 resolv
 restructuredtext
@@ -256,10 +246,6 @@ ubuntu
 udev
 udp
 un
-unconfigured
-unentitled
-unredacted
-unrendered
 url
 urls
 userdata

doc/rtd/tutorial/index.rst

@@ -3,47 +3,35 @@
 Tutorials
 *********
 
-This section contains step-by-step tutorials to help you get started with
-``cloud-init``. We hope our tutorials make as few assumptions as possible and
-are accessible to anyone with an interest in ``cloud-init``. They should be a
-great place to start learning about ``cloud-init``, how it works, and what it's
-capable of.
+Our step-by-step tutorials will help you learn about cloud-init and what it can
+do.
 
------
+New user tutorial
+=================
 
-Core tutorial
-=============
+If you are completely new to cloud-init and would like a more thorough
+introduction, we suggest starting with the
+:ref:`new user tutorial <tutorial_qemu>`.
 
-This tutorial, which we recommend if you are completely new to ``cloud-init``,
-uses the QEMU emulator to introduce you to all of the key concepts, tools,
-processes and operations that you will need to get started.
+This tutorial uses the QEMU emulator to introduce you to all of the key
+concepts, tools, processes and operations that you will need to use cloud-init
+successfully.
 
-.. toctree::
-   :maxdepth: 1
+Further tutorials
+=================
 
-   qemu.rst
+This tutorial is recommended if you have some familiarity with cloud-init's key
+concepts already. It uses LXD containers to show more of cloud-init's
+capabilities.
 
-Quick-start tutorial
-====================
+* :ref:`Part 1: quick deployment <tutorial_lxd>`
 
-This tutorial is recommended if you have some familiarity with ``cloud-init``
-or the concepts around it, and are looking to get started as quickly as
-possible. Here, you will use an LXD container to deploy a ``cloud-init``
-user data script.
+  Here we deploy a cloud-init user data script into a LXD container. It
+  can also be used as a quick-start guide.
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
+   qemu.rst
    lxd.rst
-
-WSL tutorial
-============
-
-This tutorial is for learning to use ``cloud-init`` within a ``WSL``
-environment. You will use a ``cloud-init`` user data script to customize a
-``WSL`` instance.
-
-.. toctree::
-   :maxdepth: 1
-
-   wsl.rst