feat: add guide on how to create slice definitions (#15)

Rafid Bin Mostofa · cjdcordeiro · clay-lake · web-flow · commit 127a59325942 · 2025-04-28T17:50:48.000+02:00
---------

Signed-off-by: Cristovao Cordeiro &lt;cristovao.cordeiro@canonical.com&gt;
Co-authored-by: Cristovao Cordeiro &lt;cristovao.cordeiro@canonical.com&gt;
Co-authored-by: Adrian Clay Lake &lt;clay.lake@canonical.com&gt;
Co-authored-by: Yana Hontyk &lt;yana.hontyk@canonical.com&gt;
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
@@ -4,17 +4,26 @@ Dockerfile
 GID
 Levenshtein
 OpenPGP
+OpenSSL
+OpenSSL's
 PPAs
 SBOM
+SDF
 SDFs
 Starlark
 Subcommands
 UID
 ZSTD
+amd
+amd64
+analyze
 armor
 armored
 basename
+behavior
 chiseled
+conffiles
+config
 distroless
 entrypoint
 esm
@@ -24,14 +33,19 @@ http
 https
 initialize
 jsonwall
+linters
+manpages
+openssl
 optimize
 recognized
+repo
 rootfs
 runtime
 schemas
 subcommand
 subcommands
 symlink
+symlinks
 ubuntu
 whitespace
 yaml
diff --git a/docs/.sphinx/_static/js/checkbox.js b/docs/.sphinx/_static/js/checkbox.js
@@ -0,0 +1,5 @@
+document.addEventListener("DOMContentLoaded", () => {
+    document.querySelectorAll("input[type='checkbox'][disabled]").forEach(cb => {
+        cb.removeAttribute("disabled");
+    });
+});
diff --git a/docs/conf.py b/docs/conf.py
@@ -145,17 +145,16 @@
     # TODO: To enable or disable the Previous / Next buttons at the bottom of pages
     # Valid options: none, prev, next, both
     "sequential_nav": "both",
-
-    # Required for feedback button    
-    'github_issues': 'enabled',
+    # Required for feedback button
+    "github_issues": "enabled",
 }
 
 # Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897
 #
 # TODO: If your documentation is hosted on https://docs.ubuntu.com/,
 #       uncomment and update as needed.
 
-slug = 'chisel'
+slug = "chisel"
 
 
 # Template and asset locations
@@ -206,7 +205,9 @@
 # NOTE: By default, the following MyST extensions are enabled:
 #       substitution, deflist, linkify
 
-# myst_enable_extensions = set()
+myst_enable_extensions = set(
+    ["substitution", "deflist", "linkify", "tasklist", "attrs_inline"]
+)
 
 
 # Custom Sphinx extensions; see
@@ -249,12 +250,14 @@
 
 # Adds custom JavaScript files, located under 'html_static_path'
 
-# html_js_files = []
+html_js_files = [
+    "js/checkbox.js",
+]
 
 
 # Specifies a reST snippet to be appended to each .rst file
 
-if os.path.exists('./reuse/links.txt'):
+if os.path.exists("./reuse/links.txt"):
     rst_epilog = """
     .. include:: /reuse/links.txt
     """
@@ -263,8 +266,8 @@
 # formatting, use substitutions.
 # https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/#substitution
 
-if os.path.exists('./reuse/substitutions.yaml'):
-  with open('./reuse/substitutions.yaml', 'r') as fd:
+if os.path.exists("./reuse/substitutions.yaml"):
+    with open("./reuse/substitutions.yaml", "r") as fd:
         myst_substitutions = yaml.safe_load(fd.read())
 
 # Feedback button at the top; enabled by default
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -39,3 +39,15 @@ with Ubuntu Pro.
 
 install-pro-package-slices
 ```
+
+
+## Creating a slice definition
+
+Creating slice definitions can be simple and fun. Make sure to follow the best
+practices.
+
+```{toctree}
+:maxdepth: 1
+
+slice-a-package
+```
diff --git a/docs/how-to/slice-a-package.md b/docs/how-to/slice-a-package.md
