From f6f253986c40a1f4b2ca30979681c27b9d184e5a Mon Sep 17 00:00:00 2001 From: Jakob Unterwurzacher Date: Thu, 27 Oct 2022 11:19:58 +0200 Subject: [PATCH] godoc: fix mangled yaml code blocks, take two Unfortunatley, 191c474477af4cc679779dd4eb70f28c1d9dbd62 was not enough to fix the yaml code block rendering on godoc.org. The problem is that a block that starts with "-", even if indented, is interpreted as a list. The only solution I found was to pull the "Yaml syntax:" line into the code block as a comment. This fixes the rendering of the code block as verified by running "go doc actions" on the command line (see below): Rendering of the YAML block using "go doc actions | head -20", before this change: package actions // import "github.com/go-debos/debos/actions" Package 'actions' implements 'debos' modules used for OS creation. # Apt Action Install packages and their dependencies to the target rootfs with 'apt'. Yaml syntax: - action: apt recommends: bool unauthenticated: bool update: bool packages: - package1 - package2 Mandatory properties: - packages -- list of packages to install Optional properties: After this change: package actions // import "github.com/go-debos/debos/actions" Package 'actions' implements 'debos' modules used for OS creation. # Apt Action Install packages and their dependencies to the target rootfs with 'apt'. # Yaml syntax: - action: apt recommends: bool unauthenticated: bool update: bool packages: - package1 - package2 Mandatory properties: - packages -- list of packages to install --- actions/apt_action.go | 3 +-- actions/debootstrap_action.go | 3 +-- actions/download_action.go | 3 +-- actions/filesystem_deploy_action.go | 3 +-- actions/image_partition_action.go | 12 ++++-------- actions/ostree_commit_action.go | 3 +-- actions/ostree_deploy_action.go | 3 +-- actions/overlay_action.go | 3 +-- actions/pack_action.go | 3 +-- actions/raw_action.go | 3 +-- actions/recipe_action.go | 3 +-- actions/run_action.go | 3 +-- actions/unpack_action.go | 3 +-- 13 files changed, 16 insertions(+), 32 deletions(-) diff --git a/actions/apt_action.go b/actions/apt_action.go index 1fb275c..82267a5 100644 --- a/actions/apt_action.go +++ b/actions/apt_action.go @@ -3,8 +3,7 @@ Apt Action Install packages and their dependencies to the target rootfs with 'apt'. -Yaml syntax: - + # Yaml syntax: - action: apt recommends: bool unauthenticated: bool diff --git a/actions/debootstrap_action.go b/actions/debootstrap_action.go index e354ff4..bd3eea5 100644 --- a/actions/debootstrap_action.go +++ b/actions/debootstrap_action.go @@ -7,8 +7,7 @@ Please keep in mind -- file `/etc/resolv.conf` will be removed after execution. Most of the OS scripts used by `debootstrap` copy `resolv.conf` from the host, and this may lead to incorrect configuration when becoming part of the created rootfs. -Yaml syntax: - + # Yaml syntax: - action: debootstrap mirror: URL suite: "name" diff --git a/actions/download_action.go b/actions/download_action.go index d5d4528..e664e5f 100644 --- a/actions/download_action.go +++ b/actions/download_action.go @@ -3,8 +3,7 @@ Download Action Download a single file from Internet and unpack it in place if needed. -Yaml syntax: - + # Yaml syntax: - action: download url: http://example.domain/path/filename.ext name: firmware diff --git a/actions/filesystem_deploy_action.go b/actions/filesystem_deploy_action.go index ce441a1..094fb16 100644 --- a/actions/filesystem_deploy_action.go +++ b/actions/filesystem_deploy_action.go @@ -9,8 +9,7 @@ action requires 'image-partition' action to be executed before it. After this action has ran, subsequent actions are executed on the mounted output image. -Yaml syntax: - + # Yaml syntax: - action: filesystem-deploy setup-fstab: bool setup-kernel-cmdline: bool diff --git a/actions/image_partition_action.go b/actions/image_partition_action.go index ddf17b5..6e6d7e6 100644 --- a/actions/image_partition_action.go +++ b/actions/image_partition_action.go @@ -7,8 +7,7 @@ build, and optionally (but by-default) mounted at boot in the final system. The mountpoints are sorted on their position in the filesystem hierarchy so the order in the recipe does not matter. -Yaml syntax: - + # Yaml syntax: - action: image-partition imagename: image_name imagesize: size @@ -46,8 +45,7 @@ should be in GUID format (e.g.: '00002222-4444-6666-AAAA-BBBBCCCCFFFF' where eac character is an hexadecimal digit). For 'msdos' partition table, 'diskid' should be a 32 bits hexadecimal number (e.g. '1234ABCD' without any dash separator). -Yaml syntax for partitions: - + # Yaml syntax for partitions: partitions: - name: partition name partlabel: partition label @@ -108,8 +106,7 @@ ext2, ext3, ext4 and xfs. - extendedoptions -- list of additional filesystem extended options which need to be enabled for the partition. -Yaml syntax for mount points: - + # Yaml syntax for mount points: mountpoints: - mountpoint: path partition: partition label @@ -135,8 +132,7 @@ to define a `mountpoint` path which is temporary and unique for the image, for example: `/mnt/temporary_mount`. Defaults to false. -Layout example for Raspberry PI 3: - + # Layout example for Raspberry PI 3: - action: image-partition imagename: "debian-rpi3.img" imagesize: 1GB diff --git a/actions/ostree_commit_action.go b/actions/ostree_commit_action.go index 5011ae9..64a279e 100644 --- a/actions/ostree_commit_action.go +++ b/actions/ostree_commit_action.go @@ -3,8 +3,7 @@ OstreeCommit Action Create OSTree commit from rootfs. -Yaml syntax: - + # Yaml syntax: - action: ostree-commit repository: repository name branch: branch name diff --git a/actions/ostree_deploy_action.go b/actions/ostree_deploy_action.go index 56f3bde..e4249e4 100644 --- a/actions/ostree_deploy_action.go +++ b/actions/ostree_deploy_action.go @@ -7,8 +7,7 @@ during this step. Action 'image-partition' must be called prior to OSTree deploy. -Yaml syntax: - + # Yaml syntax: - action: ostree-deploy repository: repository name remote_repository: URL diff --git a/actions/overlay_action.go b/actions/overlay_action.go index f7f91d0..44a22b2 100644 --- a/actions/overlay_action.go +++ b/actions/overlay_action.go @@ -3,8 +3,7 @@ Overlay Action Recursive copy of directory or file to target filesystem. -Yaml syntax: - + # Yaml syntax: - action: overlay origin: name source: directory diff --git a/actions/pack_action.go b/actions/pack_action.go index acaefa9..0e869c6 100644 --- a/actions/pack_action.go +++ b/actions/pack_action.go @@ -3,8 +3,7 @@ Pack Action Create tarball with filesystem. -Yaml syntax: - + # Yaml syntax: - action: pack file: filename.ext compression: gz diff --git a/actions/raw_action.go b/actions/raw_action.go index f44727b..0807a17 100644 --- a/actions/raw_action.go +++ b/actions/raw_action.go @@ -4,8 +4,7 @@ Raw Action Directly write a file to the output image at a given offset. This is typically useful for bootloaders. -Yaml syntax: - + # Yaml syntax: - action: raw origin: name source: filename diff --git a/actions/recipe_action.go b/actions/recipe_action.go index e9b13ed..860faa6 100644 --- a/actions/recipe_action.go +++ b/actions/recipe_action.go @@ -11,8 +11,7 @@ passed in the "architecture" template variable. Limitations of combined recipes are equivalent to limitations within a single recipe (e.g. there can only be one image partition action). -Yaml syntax: - + # Yaml syntax: - action: recipe recipe: path to recipe variables: diff --git a/actions/run_action.go b/actions/run_action.go index 2c198c5..af7fc79 100644 --- a/actions/run_action.go +++ b/actions/run_action.go @@ -5,8 +5,7 @@ Allows to run any available command or script in the filesystem or in build process host environment: specifically inside the fakemachine created by Debos. -Yaml syntax: - + # Yaml syntax: - action: run chroot: bool postprocess: bool diff --git a/actions/unpack_action.go b/actions/unpack_action.go index 93a4692..8c7eac4 100644 --- a/actions/unpack_action.go +++ b/actions/unpack_action.go @@ -6,8 +6,7 @@ Useful for creating target rootfs from saved tarball with prepared file structur Only (compressed) tar archives are supported currently. -Yaml syntax: - + # Yaml syntax: - action: unpack origin: name file: file.ext