Add docs gen and cleanup readme (#57)

Author: jahvon

README.md

@@ -1,56 +1,22 @@
-# flow - Local, CLI Workflow Manager
+# flow - One CLI to manage all your development workflows and systems
 
-## Configuration and Workflow Definition Files
+[![Go Report Card](https://goreportcard.com/badge/github.com/jahvon/flow)](https://goreportcard.com/report/github.com/jahvon/flow)
+[![Go Reference](https://pkg.go.dev/badge/github.com/jahvon/flow.svg)](https://pkg.go.dev/github.com/jahvon/flow)
+[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/jahvon/flow)](
 
-`flow` uses a configuration file to define the workspaces and workflows that it manages. 
-The location for this flow configuration file is `~/.flow/config.yaml`. Below is an example of a flow configuration file.
+## Getting Started
 
-```yaml
-currentWorkspace: workspace1
-workspaces:
-  workspace1: /path/to/workspace1
-  workspace2: /path/to/workspace2
-```
-
-Workflows can be defined anywhere within a workspace's directory with the `.flow` file extension.
-Below is an example of a workflow definition file.
-
-```yaml
-namespace: ns
-tags:
-  - example
-executables:
-  - type: open
-    name: config
-    tags:
-      - config
-    description: open flow config in vscode
-    spec:
-      uri: .flow
-      application: Visual Studio Code
-```
-
-Running `flow open ns:config` will run the above workflow.
-
-## CLI Usage
-
-See [flow CLI documentation](docs/cli/flow.md) for more information.
-
-**Autocompletion**
-
-Example autocompletion setup script: `flow completion zsh > ~/.oh-my-zsh/completions/_flow`
-
-## Install
+### Installation
 
 You can install the pre-compiled binary or compile from source.
 
-### via Go Install
+#### via Go Install
 
 ```bash
 go install github.com/jahvon/flow@latest
 ```
 
-### via GitHub Releases
+#### via GitHub Releases
 
 Download the pre-compiled binaries from the [release page](https://github.com/jahvon/flow/releases) page and copy them to the desired location.
 
@@ -64,11 +30,48 @@ $ sudo tar xvf ${TAR_FILE} flow -C /usr/local/bin
 $ rm -f ${TAR_FILE}
 ```
 
-### via Source
+#### via Source
 
 ```bash
 $ git clone github.com/jahvon/flow
 $ cd flow
 $ go generate ./...
 $ go install
 ```
+
+### Setting up a Workspace
+
+A Workspace is a directory that contains workflows and configuration files for `flow` to manage.
+A workspace can be created anywhere on your system but must be registered in the User Config file in order to
+have executables discovered by `flow`.
+
+To create a new workspace:
+    
+```bash
+flow init workspace <name> <path>
+```
+
+This command will register the Workspace and create the root config file for you.
+For more information on Workspaces and it's config, see [Workspaces](docs/config/workspace_config.md).
+
+### Defining Executables
+
+Executables are the core of `flow`. They are the workflows that `flow` will execute when running a workflow.
+Each executable is driven by its definition within an executable definition file (`*.flow` file). There are
+several types of executables that can be defined. 
+For more information on Executables and it's config, see [Executables](docs/config/executables.md).
+
+
+### Running and managing workflows
+
+The main command for running workflows is `flow exec`. This command will execute the workflow with the provided
+executable ID. `exec` can be replaced with any verb but should match the verb defined in the executable's definition or
+an alias of the verb.
+
+As you make changes to executables on your system, you can run `flow sync` to trigger a re-index of your executables.
+
+See [flow CLI documentation](docs/cli/flow.md) for more information on all available commands.
+
+**Autocompletion**
+
+Example autocompletion setup script: `flow completion zsh > ~/.oh-my-zsh/completions/_flow`

cmd/common.go

@@ -136,5 +136,6 @@ func exitApp(_ *cobra.Command, _ []string) {
 }
 
 func GenerateMarkdownTree(dir string) error {
+	rootCmd.DisableAutoGenTag = true
 	return doc.GenMarkdownTree(rootCmd, dir)
 }

cmd/exec.go

@@ -29,8 +29,8 @@ var execCmd = &cobra.Command{
 	Short:   "Execute a flow by ID.",
 	Long: "Execute a flow where <executable-id> is the target executable's ID in the form of 'ws/ns:name'.\n" +
 		"The flow subcommand used should match the target executable's verb or one of its aliases.\n\n" +
-		"See " + io.DocsURL("executable-verbs") + "for more information on executable verbs." +
-		"See " + io.DocsURL("executable-ids") + "for more information on executable IDs.",
+		"See " + io.ConfigDocsURL("executables", "Verb") + "for more information on executable verbs." +
+		"See " + io.ConfigDocsURL("executables", "Ref") + "for more information on executable IDs.",
 	Args: cobra.ExactArgs(1),
 	PreRun: func(cmd *cobra.Command, args []string) {
 		startApp(cmd, args)

cmd/get.go

@@ -95,8 +95,8 @@ var executableGetCmd = &cobra.Command{
 	Short:   "Print an executable flow by reference.",
 	Long: "Print an executable by the executable's verb and ID.\nThe target executable's ID should be in the  " +
 		"form of 'ws/ns:name' and the verb should match the target executable's verb or one of its aliases.\n\n" +
-		"See" + io.DocsURL("executable-verbs") + "for more information on executable verbs." +
-		"See" + io.DocsURL("executable-ids") + "for more information on executable IDs.",
+		"See" + io.ConfigDocsURL("executables", "Verb") + "for more information on executable verbs." +
+		"See" + io.ConfigDocsURL("executable", "Ref") + "for more information on executable IDs.",
 	Args:    cobra.ExactArgs(2),
 	PreRun:  startApp,
 	PostRun: waitForExit,

config/common.go

@@ -14,6 +14,15 @@ const (
 	LaunchGroupID     = "launch"
 )
 
+// +docsgen:verb
+// Keywords that describe the action an executable performs.
+// While executables are configured with a single verb, the verb can be aliased to related verbs.
+// For example, the `exec` verb can replaced with "run" or "start" when referencing an executable.
+// This allows users to use the verb that best describes the action they are performing.
+//
+// **Activation verbs**: `exec`, `run`, `start`, `install`, `setup`
+// **Deactivation verbs**: `delete`, `remove`, `uninstall`, `teardown`, `destroy`
+// **Launch verbs**: `open`, `launch`, `edit`, `show`, `view`, `render`, `process`, `transform`, `generate`
 type Verb string
 
 var (
@@ -116,6 +125,9 @@ func (v VisibilityType) IsHidden() bool {
 	return v == VisibilityHidden
 }
 
+// +docsgen:tags
+// A list of tags.
+// Tags can be used with list commands to filter returned data.
 type Tags []string
 
 func (t Tags) String() string {
@@ -173,6 +185,14 @@ func (a Aliases) HasAlias(alias string) bool {
 	return false
 }
 
+// +docsgen:ref
+// A reference to an executable.
+// The format is `<verb> <workspace>/<namespace>:<executable name>`.
+// For example, `exec ws/ns:my-flow`.
+//
+// The workspace and namespace are optional.
+// If the workspace is not specified, the current workspace will be used.
+// If the namespace is not specified, the current namespace will be used.
 type Ref string
 
 func NewRef(id string, verb Verb) Ref {

config/executable_definitions.go

@@ -5,9 +5,23 @@ import (
 )
 
 type ExecutableDefinition struct {
-	Namespace   string         `yaml:"namespace"`
-	Tags        Tags           `yaml:"tags"`
-	Visibility  VisibilityType `yaml:"visibility"`
+	// +docsgen:namespace
+	// The namespace of the executable definition. This is used to group executables together.
+	// If not set, the executables in the definition will be grouped into the root (*) namespace.
+	// Namespaces can be reused across multiple definitions.
+	Namespace string `yaml:"namespace"`
+	Tags      Tags   `yaml:"tags"`
+	// +docsgen:visibility
+	// The visibility of the executables to Flow.
+	// If not set, the visibility will default to `public`.
+	//
+	// `public` executables can be executed and listed from anywhere.
+	// `private` executables can be executed and listed only within their own workspace.
+	// `internal` executables can be executed within their own workspace but are not listed.
+	// `hidden` executables cannot be executed or listed.
+	Visibility VisibilityType `yaml:"visibility"`
+	// +docsgen:executables
+	// A list of executables to be defined in the executable definition.
 	Executables ExecutableList `yaml:"executables"`
 
 	workspaceName, workspacePath, definitionPath string

config/executables.go

@@ -18,6 +18,13 @@ import (
 const tmpdir = "f:tmp"
 
 type DirectoryScopedExecutable struct {
+	// +docsgen:dir
+	// The directory to execute the command in.
+	// If unset, the directory of the executable definition will be used.
+	// If set to `f:tmp`, a temporary directory will be created for the process.
+	// If prefixed with `./`, the path will be relative to the current working directory.
+	// If prefixed with `//`, the path will be relative to the workspace root.
+	// Environment variables in the path will be expended at runtime.
 	Directory string `yaml:"dir"`
 }
 
@@ -41,6 +48,8 @@ func (e *DirectoryScopedExecutable) ExpandDirectory(
 }
 
 type ParameterizedExecutable struct {
+	// +docsgen:params
+	// List of parameters to pass to the executable.
 	Parameters ParameterList `yaml:"params"`
 }
 
@@ -104,6 +113,8 @@ type RenderExecutableType struct {
 type SerialExecutableType struct {
 	ParameterizedExecutable `yaml:",inline"`
 
+	// +docsgen:refs
+	// List of executables references
 	ExecutableRefs []Ref `yaml:"refs"`
 	FailFast       bool  `yaml:"failFast"`
 }
@@ -117,23 +128,37 @@ type ParallelExecutableType struct {
 }
 
 type ExecutableTypeSpec struct {
-	Exec     *ExecExecutableType     `yaml:"exec,omitempty"`
-	Launch   *LaunchExecutableType   `yaml:"launch,omitempty"`
-	Request  *RequestExecutableType  `yaml:"request,omitempty"`
-	Render   *RenderExecutableType   `yaml:"render,omitempty"`
-	Serial   *SerialExecutableType   `yaml:"serial,omitempty"`
+	// +docsgen:exec
+	// Standard executable type. Runs a command/file in a subprocess.
+	Exec *ExecExecutableType `yaml:"exec,omitempty"`
+	// +docsgen:launch
+	// Launches an application or opens a URI.
+	Launch *LaunchExecutableType `yaml:"launch,omitempty"`
+	// +docsgen:request
+	// Makes an HTTP request.
+	Request *RequestExecutableType `yaml:"request,omitempty"`
+	// +docsgen:render
+	// Renders a Markdown template with provided data. Requires the Interactive UI.
+	Render *RenderExecutableType `yaml:"render,omitempty"`
+	// +docsgen:serial
+	// Runs a list of executables in serial.
+	Serial *SerialExecutableType `yaml:"serial,omitempty"`
+	// +docsgen:parallel
+	// Runs a list of executables in parallel.
 	Parallel *ParallelExecutableType `yaml:"parallel,omitempty"`
 }
 
 type Executable struct {
-	Verb        Verb                `yaml:"verb"`
-	Name        string              `yaml:"name"`
-	Aliases     []string            `yaml:"aliases"`
-	Tags        Tags                `yaml:"tags"`
-	Description string              `yaml:"description"`
-	Visibility  VisibilityType      `yaml:"visibility"`
-	Timeout     time.Duration       `yaml:"timeout"`
-	Type        *ExecutableTypeSpec `yaml:"type"`
+	Verb        Verb           `yaml:"verb"`
+	Name        string         `yaml:"name"`
+	Aliases     []string       `yaml:"aliases"`
+	Tags        Tags           `yaml:"tags"`
+	Description string         `yaml:"description"`
+	Visibility  VisibilityType `yaml:"visibility"`
+	Timeout     time.Duration  `yaml:"timeout"`
+	// +docsgen:type
+	// The type of executable. Only one type can be set.
+	Type *ExecutableTypeSpec `yaml:"type"`
 
 	workspace, namespace, workspacePath, definitionPath string
 }

config/parameter.go

@@ -9,12 +9,22 @@ import (
 	"github.com/jahvon/flow/internal/utils"
 )
 
+// +docsgen:param
+// A parameter is a value that can be passed to an executable and all of its sub-executables.
+// Only one of `text`, `secretRef`, or `prompt` must be set. Specifying more than one will result in an error.
 type Parameter struct {
-	// Only one of text, secretRef, or prompt should be set.
-	Text      string `yaml:"text"`
-	Prompt    string `yaml:"prompt"`
+	// +docsgen:text
+	// A static value to be passed to the executable.
+	Text string `yaml:"text"`
+	// +docsgen:secretRef
+	// A reference to a secret to be passed to the executable.
+	Prompt string `yaml:"prompt"`
+	// +docsgen:prompt
+	// A prompt to be displayed to the user to collect a value to be passed to the executable.
 	SecretRef string `yaml:"secretRef"`
 
+	// +docsgen:envKey
+	// The name of the environment variable that will be set with the value of the parameter.
 	EnvKey string `yaml:"envKey"`
 }
 

config/user_config.go

@@ -8,15 +8,28 @@ import (
 )
 
 type InteractiveConfig struct {
-	Enabled            bool `json:"enabled" yaml:"enabled"`
-	NotifyOnCompletion bool `json:"notify"  yaml:"notify"`
-	SoundOnCompletion  bool `json:"sound"   yaml:"sound"`
+	Enabled bool `json:"enabled" yaml:"enabled"`
+	// +docsgen:notify
+	// Whether to send a desktop notification when a command completes.
+	NotifyOnCompletion bool `json:"notify" yaml:"notify"`
+	// +docsgen:sound
+	// Whether to play a sound when a command completes.
+	SoundOnCompletion bool `json:"sound" yaml:"sound"`
 }
+
 type UserConfig struct {
-	Workspaces       map[string]string  `json:"workspaces"       yaml:"workspaces"`
-	CurrentWorkspace string             `json:"currentWorkspace" yaml:"currentWorkspace"`
-	CurrentNamespace string             `json:"currentNamespace" yaml:"currentNamespace"`
-	Interactive      *InteractiveConfig `json:"interactive"      yaml:"interactive"`
+	// +docsgen:workspaces
+	// Map of workspace names to their paths.
+	Workspaces map[string]string `json:"workspaces" yaml:"workspaces"`
+	// +docsgen:currentWorkspace
+	// The name of the current workspace. This should match a key in the `workspaces` map.
+	CurrentWorkspace string `json:"currentWorkspace" yaml:"currentWorkspace"`
+	// +docsgen:currentNamespace
+	// The name of the current namespace. This is not required to be set.
+	CurrentNamespace string `json:"currentNamespace" yaml:"currentNamespace"`
+	// +docsgen:interactive
+	// Configurations for the interactive UI.
+	Interactive *InteractiveConfig `json:"interactive" yaml:"interactive"`
 }
 
 func (c *UserConfig) Validate() error {

config/workspace_config.go

@@ -11,6 +11,8 @@ import (
 )
 
 type WorkspaceConfig struct {
+	// +docsgen:displayName
+	// The display name of the workspace. This is used in the interactive UI.
 	DisplayName string                    `json:"displayName"           yaml:"displayName"`
 	Description string                    `json:"description,omitempty" yaml:"description,omitempty"`
 	Tags        Tags                      `json:"tags,omitempty"        yaml:"tags,omitempty"`
@@ -24,12 +26,19 @@ type WorkspaceConfig struct {
 type WorkspaceConfigList []WorkspaceConfig
 
 type GitConfig struct {
-	Enabled    bool `json:"enabled"              yaml:"enabled"`
+	Enabled bool `json:"enabled" yaml:"enabled"`
+
+	// +docsgen:pullOnSync
+	// Whether to pull the latest changes from the remote when syncing.
 	PullOnSync bool `json:"pullOnSync,omitempty" yaml:"pullOnSync,omitempty"`
 }
 
 type ExecutableLocationConfig struct {
+	// +docsgen:included
+	// A list of directories to include in the executable search.
 	Included []string `json:"included,omitempty" yaml:"included,omitempty"`
+	// +docsgen:excluded
+	// A list of directories to exclude from the executable search.
 	Excluded []string `json:"excluded,omitempty" yaml:"excluded,omitempty"`
 }