Add generated documentation for Unix devices

[stgraber]

Incus is slowly moving to automatically generated documentation for its configuration keys.

This can be done through the gendoc:generate type comments in the code, followed by running make update-metadata and consumption in the documentation through {include} ../config-option.txt.

This issue is for the keys defined in doc/reference/device_unix_block.md, doc/reference/device_unix_char.md, doc/reference/device_unix_hotplug.md to be moved to code in internal/server/device/unix_common.go and internal/server/device/unix_hotplug.go.

[milaiwi]

Can I get this assigned? I'm thinking we essentially have to add gendoc:generate comments to the structs defined in the *.go files that include information outlined in the *.md (Key, Type, Default Description). It would just be three different commits, something like:

internal/device/unix_hotplug.go: Added gendoc:generate comments for automatic documentation generation.

[stgraber]

Assigned it to you, and yeah, that's right. We usually put the gendoc:generate comment just above where we have the config key validation logic validate.IsXYZ so that anyone modifying the validation logic will see the documentation and update it at the same time.

[milaiwi]

for gendoc:generate, what would the parameters for something like this be? I tried to find documentation for this but couldn't. I'm thinking something like gendoc:generate(entity=instance, group=miscallaneous, key=unix_hotplug_devices.gid). So if we're generating for something like this:

 Key         | Type      | Default           | Description
 :--         | :--       | :--               | :--
 `gid`       | int       | `0`               | GID of the device owner in the instance

We'd write something like:

      // gendoc:generate(entity=instance, group=miscallaneous, key=unix_hotplug_devices.gid)
      //
      // ---
      //  key: gid
      //  type: int
      //  default: 0
      //  shortdesc: GID of the device owner in the instance
      "unix_hotplug_devices.gid": validate.Optional(validate.IsInt)

[stgraber]

Maybe:

• entity: instance_device
• group: unix-hotplug
• key: gid

[milaiwi]

I made a pull request and tested the documentation on localhost. I've ran into issues with passing the make doc-spellcheck test and get this error:

The HTML pages are in doc/html.
. doc/.sphinx/venv/bin/activate ; python3 -m pyspelling -c doc/.sphinx/spellingcheck.yaml
['aspell', '--lang', 'en', '--encoding', 'utf-8', 'create', 'master', '/home/ubuntu/incus/doc/.sphinx/.wordlist.dic']
Current wordlist: 'doc/.wordlist.txt'
Problem compiling dictionary. Check the binary path and options.
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/__main__.py", line 97, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/__main__.py", line 37, in main
    return run(
           ^^^^
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/__main__.py", line 64, in run
    for results in spellcheck(
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/__init__.py", line 742, in spellcheck
    for result in spelltask.run_task(task, source_patterns=sources):
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/__init__.py", line 657, in run_task
    self.personal_dict = self.spellchecker.setup_dictionary(self.task, self.binary, self.verbose)
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/__init__.py", line 273, in setup_dictionary
    cls.compile_dictionary(
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/__init__.py", line 315, in compile_dictionary
    util.call(
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/util/__init__.py", line 97, in call
    process = get_process(cmd)
              ^^^^^^^^^^^^^^^^
  File "/home/ubuntu/incus/doc/.sphinx/venv/lib/python3.12/site-packages/pyspelling/util/__init__.py", line 66, in get_process
    process = subprocess.Popen(
              ^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/subprocess.py", line 1026, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
  File "/usr/lib/python3.12/subprocess.py", line 1955, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
FileNotFoundError: [Errno 2] No such file or directory: 'aspell'
make: *** [Makefile:175: doc-spellcheck] Error 1

I've been having trouble tracing the issue, though.