Include manpages for lima and limactl commands

[afbjorklund]

The "limactl.1" and subcommands are being dynamically generated.

There is one manual page for each subcommand, e.g. limactl-start

---

https://github.com/spf13/cobra/blob/main/doc/man_docs.md

There is also help2man --no-info, for individual commands

[afbjorklund]

Here is the lima.1, in markdown:

LIMA 1 "May 2023" "" ""
=======================

# NAME
lima - Lima: Linux virtual machines

# SYNOPSIS
**lima** [_COMMAND_...]

# DESCRIPTION
lima is an alias for "limactl shell default".
The instance name ("default") can be changed by specifying $LIMA\_INSTANCE.

The shell and initial workdir inside the instance can be specified via $LIMA\_SHELL
and $LIMA\_WORKDIR.

# SEE ALSO
**limactl**(1)

[AkihiroSuda]

CI is failing

_output/bin/limactl generate-man _output/share/man/man1
time="2023-05-03T07:06:14Z" level=fatal msg="must not run as the root"

We can just allow generate-man for root

[AkihiroSuda]

Thanks

[jandubois]

The PR seems fine.

The auto-generated man pages look a bit sparse (I just compared man limactl-start with man git-commit and man kubectl-get). I guess it would be a matter of improving the Cobra definitions for each command.

I also noticed that git commit --help will invoke man git-commit, which has better formatting than what Cobra does. I wonder if this is something we should consider (fwiw, kubectl doesn't delegate to man).

[afbjorklund]

I think we should just use the default cobra output, and improve the descriptions in the code if it is needed.

We could also generate markdown, and use that for a standalone documentation - like in a docs web site

https://github.com/spf13/cobra/blob/main/doc/md_docs.md

• Web site (https://lima-vm.io/): migrate to docsy, mkdocs, gitbook, or something else #1499

[jandubois]

I think we should just use the default cobra output, and improve the descriptions in the code if it is needed.

That's what I meant by "improving the Cobra definitions". Having separate (duplicate) docs for each subcommands is just not maintainable.

[afbjorklund]

I did some experiments with generating markdown and html, from cobra:

master...afbjorklund:lima:markdown

It's not perfect, since most of it is just blocks of performatted text (at best)