Add manpages for podman-bootc

.github/workflows/ci.yml

@@ -19,6 +19,7 @@ jobs:
           # Because all the git clones are much less reliable
           export GOPROXY=https://proxy.golang.org
           go install github.com/onsi/ginkgo/v2/ginkgo@latest
+          go install github.com/cpuguy83/go-md2man@latest
           make GOOPTS=-buildvcs=false
           export PATH=$PATH:$HOME/go/bin
           make integration_tests

.gitignore

@@ -1,2 +1,3 @@
 /bin
 test/e2e/e2e.test
+docs/*.1

Makefile

@@ -2,13 +2,13 @@ binary_name = podman-bootc
 output_dir = bin
 build_tags = exclude_graphdriver_btrfs,btrfs_noversion,exclude_graphdriver_devicemapper,containers_image_openpgp,remote
 
-all: out_dir
+all: out_dir docs
 	go build -tags $(build_tags) $(GOOPTS) -o $(output_dir)/$(binary_name)
 
 out_dir:
 	mkdir -p $(output_dir)
 
-lint:
+lint: validate_docs
 	golangci-lint --build-tags $(build_tags) run
 
 integration_tests:
@@ -18,5 +18,15 @@ integration_tests:
 e2e_test: all
 	ginkgo -tags $(build_tags) ./test/...
 
+.PHONY: docs
+docs:
+	make -C docs
+
 clean:
 	rm -f $(output_dir)/*
+	make -C docs clean
+
+.PHONY: validate_docs
+validate_docs:
+	hack/man-page-checker
+	hack/xref-helpmsgs-manpages

docs/Makefile

@@ -0,0 +1,39 @@
+PREFIX := /usr/local
+DATADIR := ${PREFIX}/share
+MANDIR := $(DATADIR)/man
+GO ?= go
+GOMD2MAN ?= go-md2man
+ifeq ($(shell uname -s),FreeBSD)
+SED=gsed
+else
+SED=sed
+endif
+# This must never include the 'hack' directory
+export PATH := $(shell $(GO) env GOPATH)/bin:$(PATH)
+
+docs:  $(patsubst %.md,%,$(wildcard *[1].md))
+
+%.1: %.1.md
+### sed is used to filter http/s links as well as relative links
+### replaces "\" at the end of a line with two spaces
+### this ensures that manpages are rendered correctly
+	@$(SED) -e 's/\((podman-bootc[^)]*\.md\(#.*\)\?)\)//g' \
+	 -e 's/\[\(podman-bootc[^]]*\)\]/\1/g' \
+	 -e 's/\[\([^]]*\)](http[^)]\+)/\1/g' \
+	 -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g' \
+	 -e 's/\\$$/  /g' $<  | \
+	$(GOMD2MAN) -in /dev/stdin -out  $@
+
+.PHONY: install
+install: docs
+	install -d ${DESTDIR}/${MANDIR}/man1
+	install -m 0644 podman-bootc*.1 ${DESTDIR}/${MANDIR}/man1
+	install -m 0644 links/podman-bootc*.1 ${DESTDIR}/${MANDIR}/man1
+
+.PHONY: install-tools
+install-tools:
+	go install github.com/cpuguy83/go-md2man@latest
+
+.PHONY: clean
+clean:
+	$(RM) -f podman-bootc*.1

docs/podman-bootc-completion.1.md

@@ -0,0 +1,26 @@
+% podman-bootc-completion 1
+
+## NAME 
+podman-bootc-completion - Generate the autocompletion script for the specified shell
+
+## SYNOPSIS
+**podman-bootc completion** *bash* | *fish* | *powershell* | *zsh* [*options*]
+
+## DESCRIPTION
+**podman-bootc completion** generate shell completion scripts for a variety of shells. 
+Supported shells are *bash*, *fish*, *powershell*, and *zsh*.
+
+## OPTIONS
+
+#### **--help**, **-h**
+Show details on how to use the script generated for the particular shell.
+
+#### **--no-descriptions**
+Disable completion descriptions.
+
+## SEE ALSO
+
+**[podman-bootc(1)](podman-bootc.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>

docs/podman-bootc-images.1.md

@@ -0,0 +1,26 @@
+% podman-bootc-images 1
+
+## NAME
+podman-bootc-images - List bootc images in the local containers store
+
+## SYNOPSIS
+**podman-bootc images**
+
+## DESCRIPTION
+**podman-bootc images** list bootc images in the containers store of the podman machine.
+The podman machine must be running to use this command.
+
+## OPTIONS
+
+#### **--help**, **-h**
+Help for images
+
+#### **--log-level**=*level*
+Log messages at and above specified level: __debug__, __info__, __warn__, __error__, __fatal__ or __panic__ (default: _warn_)
+
+## SEE ALSO
+
+**[podman-bootc(1)](podman-bootc.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>

docs/podman-bootc-list.1.md

@@ -0,0 +1,27 @@
+% podman-bootc-list 1
+
+## NAME
+podman-bootc-list - List installed OS Containers
+
+## SYNOPSIS
+**podman-bootc list**
+
+## DESCRIPTION
+**podman-bootc list** displays installed OS containers and their status.
+
+The podman machine must be running to use this command.
+
+## OPTIONS
+
+#### **--help**, **-h**
+Help for list
+
+#### **--log-level**=*level*
+Log messages at and above specified level: __debug__, __info__, __warn__, __error__, __fatal__ or __panic__ (default: _warn_)
+
+## SEE ALSO
+
+**[podman-bootc(1)](podman-bootc.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>

docs/podman-bootc-rm.1.md

@@ -0,0 +1,35 @@
+% podman-bootc-rm 1
+
+## NAME
+podman-bootc-rm - Remove installed bootc VMs
+
+## SYNOPSIS
+**podman-bootc rm** *id* [*options*]
+
+## DESCRIPTION
+**podman-bootc rm** removes an installed bootc VM/container from the podman machine.
+
+Use **[podman-bootc list](podman-bootc-list.1.md)** to find the IDs of installed VMs.
+
+The podman machine must be running to use this command.
+
+## OPTIONS
+
+#### **--all**
+Removes all non-running bootc VMs
+
+#### **--force**, **-f**
+Terminate a running VM
+
+#### **--help**, **-h**
+Help for rm
+
+#### **--log-level**=*level*
+Log messages at and above specified level: __debug__, __info__, __warn__, __error__, __fatal__ or __panic__ (default: _warn_)
+
+## SEE ALSO
+
+**[podman-bootc(1)](podman-bootc.1.md)**, **[podman-bootc-list(1)](podman-bootc-list.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>

docs/podman-bootc-run.1.md

@@ -0,0 +1,66 @@
+% podman-bootc-run 1
+
+## NAME
+podman-bootc-run - Run a bootc container as a VM
+
+## SYNOPSIS
+**podman-bootc run** [*options*] *image* | *id*
+
+## DESCRIPTION
+**podman-bootc run** creates a new virtual machine from a bootc container image or starts an existing one.
+It then creates an SSH connection to the VM using injected credentials (see *--background* to run in the background).
+
+The podman machine must be running to use this command.
+
+## OPTIONS
+
+#### **--background**, **-B**
+Do not spawn SSH, run in background.
+
+#### **--cloudinit**=**string**
+--cloud-init <cloud-init data directory>
+
+#### **--disk-size**=**string**
+Allocate a disk image of this size in bytes; optionally accepts M, G, T suffixes
+
+#### **--filesystem**=**string**
+Override the root filesystem, e.g. xfs, btrfs, ext4.
+
+#### **--help**, **-h**
+Help for run
+
+#### **--log-level**=*level*
+Log messages at and above specified level: __debug__, __info__, __warn__, __error__, __fatal__ or __panic__ (default: _warn_)
+
+#### **--quiet**
+Suppress output from bootc disk creation and VM boot console
+
+#### **--rm**
+Remove the VM and it's disk image when the SSH connection exits. Cannot be used with *--background*
+
+#### **--root-size-max**=**string**
+Maximum size of root filesystem in bytes; optionally accepts M, G, T suffixes
+
+#### **--user**, **-u**=**root** | *user name*
+User name of injected user, default: root
+
+## EXAMPLES
+Create a virtual machine based on the latest bootable image from Fedora using XFS as the root filesystem.
+```
+$ podman-bootc run --filesystem=xfs quay.io/fedora/fedora-bootc:latest
+```
+
+Start a previously created VM, using *podman-bootc list* to find its ID.
+```
+$ podman-bootc list
+ID            REPO                                       SIZE        CREATED        RUNNING     SSH PORT
+d0300f628e13  quay.io/fedora/fedora-bootc:latest         10.7GB      4 minutes ago  false       34173
+$ podman-bootc run d0300f628e13
+```
+
+## SEE ALSO
+
+**[podman-bootc(1)](podman-bootc.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>

docs/podman-bootc-ssh.1.md

@@ -0,0 +1,30 @@
+% podman-bootc-ssh 1
+
+## NAME
+podman-bootc-ssh - SSH into an existing OS Container machine
+
+## SYNOPSIS
+**podman-bootc ssh** *id* [*options*]
+
+## DESCRIPTION
+**podman-bootc ssh** opens an SSH connection to a running OS container machine.
+
+Use **[podman-bootc list](podman-bootc-list.1.md)** to find the IDs of installed VMs.
+
+## OPTIONS
+
+#### **--help**, **-h**
+Help for ssh
+
+#### **--log-level**=*level*
+Log messages at and above specified level: __debug__, __info__, __warn__, __error__, __fatal__ or __panic__ (default: _warn_)
+
+#### **--user**, **-u**=**root** | *user name*
+User name to use for connection, default: root
+
+## SEE ALSO
+
+**[podman-bootc(1)](podman-bootc.1.md)**, **[podman-bootc-list(1)](podman-bootc-list.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>

docs/podman-bootc-stop.1.md

@@ -0,0 +1,25 @@
+% podman-bootc-stop 1
+
+## NAME
+podman-bootc-stop - Stop an existing OS Container machine
+
+## SYNOPSIS
+**podman-bootc stop** *id*
+
+## DESCRIPTION
+**podman-bootc stop** stops a running OS container machine.
+
+## OPTIONS
+
+#### **--help**, **-h**
+Help for stop
+
+#### **--log-level**=*level*
+Log messages at and above specified level: __debug__, __info__, __warn__, __error__, __fatal__ or __panic__ (default: _warn_)
+
+## SEE ALSO
+
+**[podman-bootc(1)](podman-bootc.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>

docs/podman-bootc.1.md

@@ -0,0 +1,43 @@
+% podman-bootc 1
+
+## NAME
+podman-bootc - Run bootable containers as a virtual machine
+
+## SYNOPSIS
+**podman-bootc** [*options*] *command*
+
+## DESCRIPTION
+**podman-bootc** is a tool to streamline the local development cycle when working with bootable containers.
+It makes it easy to run a local bootc image and get shell access to it without first setting up a virtual machine.
+
+podman-bootc requires a rootful podman machine to be running before running a bootable container.
+A machine can be set up using e.g. `podman machine init --rootful --now`. 
+See `podman-machine(1)` for details.
+
+**podman-bootc [GLOBAL OPTIONS]**
+
+## GLOBAL OPTIONS
+
+#### **--help**, **-h**
+Print usage statement
+
+#### **--log-level**=*level*
+Log messages at and above specified level: __debug__, __info__, __warn__, __error__, __fatal__ or __panic__ (default: _warn_)
+
+## COMMANDS
+
+| Command                                                    | Description                                                |
+|------------------------------------------------------------|------------------------------------------------------------|
+| [podman-bootc-completion(1)](podman-bootc-completion.1.md) | Generate the autocompletion script for the specified shell |
+| [podman-bootc-images(1)](podman-bootc-images.1.md)         | List bootc images in the local containers store            |
+| [podman-bootc-list(1)](podman-bootc-list.1.md)             | List installed OS Containers                               |
+| [podman-bootc-rm(1)](podman-bootc-rm.1.md)                 | Remove installed bootc VMs                                 |
+| [podman-bootc-run(1)](podman-bootc-run.1.md)               | Run a bootc container as a VM                              |
+| [podman-bootc-ssh(1)](podman-bootc-ssh.1.md)               | SSH into an existing OS Container machine                  |
+| [podman-bootc-stop(1)](podman-bootc-stop.1.md)             | Stop an existing OS Container machine                      |
+
+## SEE ALSO
+**[podman-machine(1)](https://github.com/containers/podman/blob/main/docs/source/markdown/podman-machine.1.md)**
+
+## HISTORY
+Dec, 2024, Originally compiled by Martin Skøtt <mskoett@redhat.com>