Doc Generation

The goal of the documentation is to make it easy for other developers to see how the plugin will behave when it's added to their Ambient app. Also, documentation is not always fun to write and keep updated so this should help!

You can automatically generate documentation for your plugin easily. Simply add this test file to the root of your project and reference your plugin. When you run go test in the root of your project, it will run your plugin in a lightweight version of Ambient, and then output a markdown README.md file in the same directory.

Sample Test File

yourplugin_test.go

package yourplugin_test

import (
    "log"
    "testing"

    "github.com/ambientkit/ambient"
    "github.com/ambientkit/ambient/pkg/ambientapp"
    "github.com/ambientkit/plugin/logger/zaplogger"
    "github.com/ambientkit/plugin/pkg/docgen"
    "github.com/ambientkit/plugin/storage/memorystorage"
)

func ExampleNew() {
    plugins := &ambient.PluginLoader{
        // Core plugins are implicitly trusted.
        Router:         nil,
        TemplateEngine: nil,
        SessionManager: nil,
        // Trusted plugins are those that are typically needed to boot so they
        // will be enabled and given full access.
        TrustedPlugins: map[string]bool{},
        Plugins: []ambient.Plugin{
            yourplugin.New(),
        },
        Middleware: []ambient.MiddlewarePlugin{
            // Middleware - executes top to bottom.
        },
    }
    _, _, err := ambientapp.NewApp("myapp", "1.0",
        zaplogger.New(),
        ambient.StoragePluginGroup{
            Storage: memorystorage.New(),
        },
        plugins)
    if err != nil {
        log.Fatalln(err.Error())
    }
}

func TestGenerateDocs(t *testing.T) {
    docgen.Generate(t, yourplugin.New(), "")
}

Generated README.md

This is an example of the README.md file that gets generated by the test code above. The docgen package handles the analysis and template generation.

The title and version are pulled from the plugin functions. The package level comment is used as the plugin description. The Example Usage section pulls the first testable example. The rest of the information is pulled by checking the plugin against interfaces and then executing functions to monitor how the plugin behaves.

README.md

# yourplugin

Package yourplugin is an Ambient plugin that does something.

**Import:** github.com/ambientkit/plugin/generic/yourplugin

**Version:** 1.0.0

## Plugin Type

The plugin can be used as the follow core types:

- **Logger:** false
- **Storage System:** false
- **Router:** false
- **Template Engine:** false
- **Session Manager:** false

## Grants

The plugin request the following grants (2):

- **Name**: plugin.setting:read
  - **Description**: Access to the yourplugin name.
- **Name**: site.asset:write
  - **Description**: Access to write a meta tag to the header.

## Settings

The plugin has the follow settings (1):

- **Name**: yourplugin
  - **Type**: input
  - **Hidden**: false

## Routes

The plugin does not have any routes.

## Middleware

The plugin does not have any middleware.

## FuncMap

The plugin does not have a FuncMap.

## Assets

The plugin does not inject any assets.

## Embedded Files

The plugin does not have any embedded files.

## Example Usage

package main

import (
    "log"

    "github.com/ambientkit/ambient"
    "github.com/ambientkit/plugin/generic/yourplugin"
    "github.com/ambientkit/plugin/logger/zaplogger"
    "github.com/ambientkit/plugin/storage/memorystorage"
)

func main() {
    plugins := &ambient.PluginLoader{
        // Core plugins are implicitly trusted.
        Router:         nil,
        TemplateEngine: nil,
        SessionManager: nil,
        // Trusted plugins are those that are typically needed to boot so they
        // will be enabled and given full access.
        TrustedPlugins: map[string]bool{},
        Plugins: []ambient.Plugin{
            yourplugin.New(),
        },
        Middleware: []ambient.MiddlewarePlugin{
            // Middleware - executes top to bottom.
        },
    }
    _, _, err := ambientapp.NewApp("myapp", "1.0",
        zaplogger.New(),
        ambient.StoragePluginGroup{
            Storage: memorystorage.New(),
        },
        plugins)
    if err != nil {
        log.Fatalln(err.Error())
    }
}

---

Docgen by [Ambient](https://ambientkit.github.io)