Annecyh/cranky tutorial suggested edits

docs/conf.py

@@ -216,6 +216,7 @@
 
 myst_enable_extensions = {
     "colon_fence",
+    "substitution",
 }
 
 # Custom Sphinx extensions; see

docs/how-to/cranking/set-up-cranky-environment.md

@@ -0,0 +1,69 @@
+# How to set up cranky environment
+
+This guide describes the one-off process to configure your build environment to
+crank Ubuntu kernels using `cranky`.
+
+## Install dependencies
+
+First, you will need to install the required packages.
+
+### Debian packages
+
+Use apt to install the following debian packages:
+
+```{code-block} text
+sudo apt install \
+    bash-completion \
+    build-essential \
+    ccache \
+    debhelper \
+    devscripts \
+    docbook-utils \
+    fakeroot \
+    gawk \
+    git \
+    git-email \
+    kernel-wedge \
+    libncurses5-dev \
+    makedumpfile \
+    python3-launchpadlib \
+    python3-ruamel.yaml \
+    schroot \
+    sharutils \
+    transfig \
+    ubuntu-dev-tools \
+    wget \
+    xmlto
+```
+
+### Snapcraft package
+
+Install snapcraft according to the Ubuntu release running on your build machine.
+
+```{tip}
+You can check your release of Ubuntu by running `lsb_release -a`.
+```
+
+`````{tab-set}
+````{tab-item} 24.04 LTS (Noble Numbat) or later
+
+Install `snapcraft` using snap:
+
+```{code-block} text
+snap install snapcraft --classic
+```
+````
+
+````{tab-item} 22.04 LTS (Jammy Jellyfish) or earlier
+
+Install `snapcraft` using apt:
+
+```{code-block} text
+sudo apt install snapcraft
+```
+````
+
+`````
+
+
+

docs/how-to/index.md

@@ -10,6 +10,7 @@ kernel packages and components.
 
 Source code access and management </how-to/source-code/index>
 Development and customization </how-to/develop-customize/index>
+Set up cranky environment </how-to/cranking/set-up-cranky-environment>
 Test kernels in -proposed </how-to/testing-verification/test-kernel-in-proposed>
 Contribute to kernel docs </how-to/contribute>
 ```
@@ -22,6 +23,14 @@ tree to build custom kernel modules, and more.
 
 - [Obtain kernel source for an Ubuntu release using Git](/how-to/source-code/obtain-kernel-source-git)
 
+## Cranking kernels
+
+In Canonical, "kernel cranking" refers to the process of applying patches and
+updates to an Ubuntu kernel, packaging it, and getting it ready for testing --
+all done using the `cranky` toolchain.
+
+- [Set up cranky environment](/how-to/cranking/set-up-cranky-environment)
+
 ## Development and customization
 
 The steps to build a kernel is similar but may have slightly difference

docs/index.md

@@ -28,7 +28,7 @@ processes for customization and maintenance.
 ```{grid-item-card} [Tutorials](/tutorial/index)
 
 **Start here**: a hands-on introduction to Ubuntu Linux kernel development for
-new users
+new users.
 ```
 
 ```{grid-item-card} [How-to guides](/how-to/index)
@@ -73,8 +73,8 @@ fixes and constructive feedback.
 :hidden:
 :maxdepth: 2
 
+/tutorial/index
 /how-to/index
 /reference/index
 /explanation/index
-/tutorial/index
 ```

docs/reference/glossary.md

@@ -47,7 +47,7 @@ linux-meta
   When a new kernel version is released and marked stable, the linux-meta
   package is updated to reference the new version, allowing automatic upgrades.  
 
-linux-signed 
+linux-signed
   Refers to kernel packages that are cryptographically signed to ensure their
   integrity and authenticity.
   These signatures are crucial for secure boot environments, as they enable the