Generate documentation

[PI-Victor]

Context

Skycrane should provide a simple straight forward way of documenting your infra

Description

Currently you can add docs strings to your starlark files, here's an example from the hetzner plugin.

"""
Hetzner infrastructure as Code

This plugin provides a way to interact with Hetzner Cloud API and manage
resources in a declarative way using starlark.

The plugin provides the following capabilities:
- Inherit process args from the host
- Inherit process stdio from the host
- Inherit process stdout from the host
- Inherit process environment from the host
- Mount files inside wasi
- Mount directory inside wasi
"""

module(
    name = "hetzner",
    version = "v0.1.0",
    # capabilities represents a set of capabilities that the plugin gains all
    # capabilities in starlark map to the capabilities of WASI and are describer here
    # https://docs.rs/wasmtime-wasi/latest/wasmtime_wasi/struct.WasiCtxBuilder.html#
    capabilities = capabilities(
        inherits = [
            # inherit process args from the host
            INHERIT_ARGS,
            # inherit process stdio from the host
            INHERIT_STDIO,
            # inherit process stdout from the host
            INHERIT_STDOUT,
            # inherit process environment from the host
            INHERIT_ENV,
        ],
        # mounts is a list of mounts that the plugin can use
        # this gives the WASI module access to the host filesystem
        mounts = [
            # mount docker socket as file inside wasi
            # add file permissions to read and write
            mount(
                host_path = "/var/run/docker.sock",
                guest_path = "/var/run/docker.sock",
                read = true,
                write = true,
                permissions_type = FILE_TYPE_PERMISSIONS,
            ),
            # mount directory inside wasi
            # add directory permissions to read and mutate
            mount(
                host_path = "/var/lib/hetzner",
                guest_path = "/mnt/hetzner",
                read = true,
                mutate = true,
                permissions_type = DIR_TYPE_PERMISSIONS,
            ),
        ],
    ),
)

And here's a proposal for how this should look like

"""
Hetzner infrastructure as Code

This plugin provides a way to interact with Hetzner Cloud API and manage
resources in a declarative way using starlark.

@capabilities:  Capabilities represents a set of capabilities that the plugin gains.
All capabilities in starlark map to capabilities of WASI and are described in the \[documentation\]\(https://docs.rs/wasmtime-wasi/latest/wasmtime_wasi/struct.WasiCtxBuilder.html\).

@mounts:  Mounts is a list of mounts that the plugin can use this gives the WASI module access to the host filesystem
"""

module(
    name = "hetzner",
    version = "v0.1.0",
    capabilities = capabilities(
        inherits = [
            INHERIT_ARGS,
            INHERIT_STDIO,
            INHERIT_STDOUT,
            INHERIT_ENV,
        ],
        mounts = [
            mount(
                host_path = "/var/run/docker.sock",
                guest_path = "/var/run/docker.sock",
                read = true,
                write = true,
                permissions_type = FILE_TYPE_PERMISSIONS,
                description = """
                  Give access to the docker socket to the plugin
                 """
            ),
            mount(
                host_path = "/var/lib/hetzner",
                guest_path = "/mnt/hetzner",
                read = true,
                mutate = true,
                permissions_type = DIR_TYPE_PERMISSIONS,
                description = """
                  Give access to /var/lib/hetzner to the plugin so that we can 
                   read and mutate the files inside of it
                 """
            ),
        ],
    ),
)

Each mount entry in the markdown will be generated straight from the starlark definition. And so would the Inherits. An idea of how this should look like when being generated to markdown:

Hetzner

Version: v1.0

Capabilities

Description: Capabilities represents a set of capabilities that the plugin gains. All capabilities in starlark map to capabilities of WASI and are described in the documentation.

Inherits:

• Stdio
• StdOut
• StdEnv
• StdArgs

Mounts:

Description: Mounts is a list of mounts that the plugin can use this gives the WASI module access to the host filesystem

• Mount type: File Host Path: "/var/run/docker.socket" Guest Path: "/var/run/docker.socket" Permissions: Read, Write Description: Mount docker socket as file inside wasi and add file permissions to read and write

• Mount type: Dir Host Path: "/var/lib/hetzner" Guest Path: "/mnt/hetzner" Permissions: Read, Mutate Description: Give access to /var/lib/hetzner to the plugin so that we can read and mutate the files inside of it

@capabilities and @mounts 

descriptions are a good way for the user to describe exactly why the plugin has been granted these capabilities and why the mounts are added.

Acceptance Criteria

• add some basic functionality for generating markdown from the starlark code

TBD.

[linear[bot]]

CLO-80 Generate documentation

[PI-Victor]

/triage /assign /label enhancement