From 45f0b393029713400ba4e6f2226ec3201b2bb3e5 Mon Sep 17 00:00:00 2001 From: Gudmundur Orri Palsson Date: Sat, 31 Jan 2026 12:01:51 +0100 Subject: [PATCH 1/4] add docs --- cmd/gendocs/main.go | 67 +++++++++++++++++++++++++++ docs/cli/daco.md | 23 +++++++++ docs/cli/daco_connections.md | 24 ++++++++++ docs/cli/daco_connections_add.md | 37 +++++++++++++++ docs/cli/daco_connections_describe.md | 39 ++++++++++++++++ docs/cli/daco_connections_list.md | 36 ++++++++++++++ docs/cli/daco_connections_remove.md | 36 ++++++++++++++ docs/cli/daco_init.md | 41 ++++++++++++++++ docs/cli/daco_ports.md | 25 ++++++++++ docs/cli/daco_ports_add.md | 41 ++++++++++++++++ docs/cli/daco_ports_describe.md | 39 ++++++++++++++++ docs/cli/daco_ports_list.md | 37 +++++++++++++++ docs/cli/daco_ports_remove.md | 38 +++++++++++++++ docs/cli/daco_ports_translate.md | 41 ++++++++++++++++ go.mod | 3 ++ go.sum | 3 ++ internal/commands/register.go | 21 +++++++-- 17 files changed, 546 insertions(+), 5 deletions(-) create mode 100644 cmd/gendocs/main.go create mode 100644 docs/cli/daco.md create mode 100644 docs/cli/daco_connections.md create mode 100644 docs/cli/daco_connections_add.md create mode 100644 docs/cli/daco_connections_describe.md create mode 100644 docs/cli/daco_connections_list.md create mode 100644 docs/cli/daco_connections_remove.md create mode 100644 docs/cli/daco_init.md create mode 100644 docs/cli/daco_ports.md create mode 100644 docs/cli/daco_ports_add.md create mode 100644 docs/cli/daco_ports_describe.md create mode 100644 docs/cli/daco_ports_list.md create mode 100644 docs/cli/daco_ports_remove.md create mode 100644 docs/cli/daco_ports_translate.md diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go new file mode 100644 index 0000000..80d2bbf --- /dev/null +++ b/cmd/gendocs/main.go @@ -0,0 +1,67 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Daco Labs + +// Command gendocs generates LLM-friendly markdown documentation for the daco CLI. +// +// Usage: +// +// go run ./cmd/gendocs [output-dir] +// +// Default output directory is ./docs/cli. +package main + +import ( + "fmt" + "os" + + "github.com/dacolabs/cli/internal/commands" + "github.com/dacolabs/cli/internal/translate" + "github.com/dacolabs/cli/internal/translate/avro" + "github.com/dacolabs/cli/internal/translate/databrickspyspark" + "github.com/dacolabs/cli/internal/translate/databricksscala" + "github.com/dacolabs/cli/internal/translate/databrickssql" + "github.com/dacolabs/cli/internal/translate/gotypes" + "github.com/dacolabs/cli/internal/translate/protobuf" + "github.com/dacolabs/cli/internal/translate/pydantic" + "github.com/dacolabs/cli/internal/translate/pyspark" + "github.com/dacolabs/cli/internal/translate/python" + "github.com/dacolabs/cli/internal/translate/scala" + "github.com/dacolabs/cli/internal/translate/sparksql" + doc "github.com/spf13/cobra/doc" +) + +func main() { + dir := "./docs/cli" + if len(os.Args) > 1 { + dir = os.Args[1] + } + + translators := make(translate.Register) + translators["pyspark"] = &pyspark.Translator{} + translators["gotypes"] = &gotypes.Translator{} + translators["avro"] = &avro.Translator{} + translators["databricks-pyspark"] = &databrickspyspark.Translator{} + translators["pydantic"] = &pydantic.Translator{} + translators["python"] = &python.Translator{} + translators["databricks-sql"] = &databrickssql.Translator{} + translators["scala"] = &scala.Translator{} + translators["spark-scala"] = &pyspark.Translator{} + translators["databricks-scala"] = &databricksscala.Translator{} + translators["protobuf"] = &protobuf.Translator{} + translators["spark-sql"] = &sparksql.Translator{} + + rootCmd := commands.NewRootCmd(translators) + rootCmd.DisableAutoGenTag = true + + if err := os.MkdirAll(dir, 0o755); err != nil { + fmt.Fprintf(os.Stderr, "error creating output dir: %v\n", err) + os.Exit(1) + } + + if err := doc.GenMarkdownTree(rootCmd, dir); err != nil { + fmt.Fprintf(os.Stderr, "error generating docs: %v\n", err) + os.Exit(1) + } + + fmt.Printf("Documentation generated in %s\n", dir) +} diff --git a/docs/cli/daco.md b/docs/cli/daco.md new file mode 100644 index 0000000..b5e8385 --- /dev/null +++ b/docs/cli/daco.md @@ -0,0 +1,23 @@ +## daco + +Data product CLI tool + +### Synopsis + +daco is a CLI for defining, managing, and translating data product specifications +using the OpenDPI standard. It supports managing ports (with JSON schemas), +infrastructure connections, and translating schemas to formats such as PySpark, +Avro, Protobuf, Go types, and more. + +### Options + +``` + -h, --help help for daco +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections +* [daco init](daco_init.md) - Initialize a new daco project +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_connections.md b/docs/cli/daco_connections.md new file mode 100644 index 0000000..ad9f2e2 --- /dev/null +++ b/docs/cli/daco_connections.md @@ -0,0 +1,24 @@ +## daco connections + +Manage data product connections + +### Synopsis + +Manage infrastructure connections defined in the OpenDPI spec. Connections +describe how to reach external systems (Kafka, PostgreSQL, S3, HTTP, etc.) +and are referenced by ports. Use subcommands to add, list, describe, or remove connections. + +### Options + +``` + -h, --help help for connections +``` + +### SEE ALSO + +* [daco](daco.md) - Data product CLI tool +* [daco connections add](daco_connections_add.md) - Add a new connection to the OpenDPI spec +* [daco connections describe](daco_connections_describe.md) - Show detailed information about a connection +* [daco connections list](daco_connections_list.md) - List all connections in the OpenDPI spec +* [daco connections remove](daco_connections_remove.md) - Remove a connection from the OpenDPI spec + diff --git a/docs/cli/daco_connections_add.md b/docs/cli/daco_connections_add.md new file mode 100644 index 0000000..23468c0 --- /dev/null +++ b/docs/cli/daco_connections_add.md @@ -0,0 +1,37 @@ +## daco connections add + +Add a new connection to the OpenDPI spec + +### Synopsis + +Add a new infrastructure connection to the OpenDPI spec. + +``` +daco connections add [flags] +``` + +### Examples + +``` + # Interactive mode + daco connections add + + # Non-interactive + daco connections add -n kafka_prod -p kafka --host broker:9092 --non-interactive +``` + +### Options + +``` + -d, --description string Description + -h, --help help for add + --host string Host/endpoint + -n, --name string Connection name + --non-interactive Run without prompts + -p, --protocol string Protocol (kafka, postgresql, mysql, s3, http, etc.) +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_connections_describe.md b/docs/cli/daco_connections_describe.md new file mode 100644 index 0000000..559e083 --- /dev/null +++ b/docs/cli/daco_connections_describe.md @@ -0,0 +1,39 @@ +## daco connections describe + +Show detailed information about a connection + +### Synopsis + +Display complete connection details including which ports use it. If no connection name is provided, an interactive selection prompt is shown. + +``` +daco connections describe [CONNECTION_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco connections describe + + # Show connection details + daco connections describe kafka_prod + + # Show as JSON + daco connections describe kafka_prod -o json + + # Show as YAML + daco connections describe kafka_prod -o yaml +``` + +### Options + +``` + -h, --help help for describe + -o, --output string Output format (text, json, yaml) (default "text") +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_connections_list.md b/docs/cli/daco_connections_list.md new file mode 100644 index 0000000..26b4bf6 --- /dev/null +++ b/docs/cli/daco_connections_list.md @@ -0,0 +1,36 @@ +## daco connections list + +List all connections in the OpenDPI spec + +### Synopsis + +List all connections defined in the OpenDPI spec with their protocols and hosts. + +``` +daco connections list [flags] +``` + +### Examples + +``` + # List connections in table format + daco connections list + + # List connections as JSON + daco connections list -o json + + # List connections as YAML + daco connections list -o yaml +``` + +### Options + +``` + -h, --help help for list + -o, --output string Output format (table, json, yaml) (default "table") +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_connections_remove.md b/docs/cli/daco_connections_remove.md new file mode 100644 index 0000000..1e29ce0 --- /dev/null +++ b/docs/cli/daco_connections_remove.md @@ -0,0 +1,36 @@ +## daco connections remove + +Remove a connection from the OpenDPI spec + +### Synopsis + +Remove a connection from the OpenDPI spec. Cannot remove connections that are in use by ports. If no connection name is provided, an interactive selection prompt is shown. + +``` +daco connections remove [CONNECTION_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco connections remove + + # Remove with confirmation + daco connections remove unused_conn + + # Remove without confirmation + daco connections remove unused_conn --force +``` + +### Options + +``` + -f, --force Skip confirmation prompt + -h, --help help for remove +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_init.md b/docs/cli/daco_init.md new file mode 100644 index 0000000..edb0d31 --- /dev/null +++ b/docs/cli/daco_init.md @@ -0,0 +1,41 @@ +## daco init + +Initialize a new daco project + +### Synopsis + +Initialize a new daco project with a daco.yaml configuration file. +Can create a new spec, use an existing one, or extend a parent config. + +``` +daco init [flags] +``` + +### Examples + +``` + # Interactive mode + daco init + + # Non-interactive + daco init --name "my-product" --non-interactive + daco init --extends ../daco.yaml --non-interactive +``` + +### Options + +``` + -e, --extends string Path to parent daco.yaml + -f, --format string Spec format (yaml or json) (default "yaml") + -h, --help help for init + -n, --name string Project name + --non-interactive Run without prompts (requires --name or --extends) + -p, --path string Path to spec folder (default "./spec") + -s, --schema-organization string Schema organization (modular, components, or inline) (default "modular") + -v, --version string Initial spec version (default "1.0.0") +``` + +### SEE ALSO + +* [daco](daco.md) - Data product CLI tool + diff --git a/docs/cli/daco_ports.md b/docs/cli/daco_ports.md new file mode 100644 index 0000000..ca487db --- /dev/null +++ b/docs/cli/daco_ports.md @@ -0,0 +1,25 @@ +## daco ports + +Manage data product ports + +### Synopsis + +Manage data product ports defined in the OpenDPI spec. Ports represent +data interfaces (input or output) with associated JSON schemas and connections. +Use subcommands to add, list, describe, remove, or translate port schemas. + +### Options + +``` + -h, --help help for ports +``` + +### SEE ALSO + +* [daco](daco.md) - Data product CLI tool +* [daco ports add](daco_ports_add.md) - Add a new port to the OpenDPI spec +* [daco ports describe](daco_ports_describe.md) - Show detailed information about a port +* [daco ports list](daco_ports_list.md) - List all ports in the OpenDPI spec +* [daco ports remove](daco_ports_remove.md) - Remove a port from the OpenDPI spec +* [daco ports translate](daco_ports_translate.md) - Translate a port schema to a target format + diff --git a/docs/cli/daco_ports_add.md b/docs/cli/daco_ports_add.md new file mode 100644 index 0000000..43a8892 --- /dev/null +++ b/docs/cli/daco_ports_add.md @@ -0,0 +1,41 @@ +## daco ports add + +Add a new port to the OpenDPI spec + +### Synopsis + +Add a new port to the OpenDPI spec with schema and connection configuration. +Ports can have optional schemas (from file or created interactively) and +connections that define where data flows. + +``` +daco ports add [flags] +``` + +### Examples + +``` + # Interactive mode + daco ports add + + # Non-interactive with existing connection + daco ports add --name events --schema-file ./schemas/event.json \ + --connection kafka --location events_topic --non-interactive +``` + +### Options + +``` + -c, --connection string Connection name + -d, --description string Port description + -h, --help help for add + -l, --location string Location (table, topic, path, etc.) + -n, --name string Port name + --non-interactive Run without prompts + -s, --schema-file string Path to JSON schema file +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_describe.md b/docs/cli/daco_ports_describe.md new file mode 100644 index 0000000..7972e7e --- /dev/null +++ b/docs/cli/daco_ports_describe.md @@ -0,0 +1,39 @@ +## daco ports describe + +Show detailed information about a port + +### Synopsis + +Display complete port definition including schema and connections. If no port name is provided, an interactive selection prompt is shown. + +``` +daco ports describe [PORT_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco ports describe + + # Show port details in human-readable format + daco ports describe user_events + + # Show port details as JSON + daco ports describe user_events -o json + + # Show port details as YAML + daco ports describe user_events -o yaml +``` + +### Options + +``` + -h, --help help for describe + -o, --output string Output format (text, json, yaml) (default "text") +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_list.md b/docs/cli/daco_ports_list.md new file mode 100644 index 0000000..c2c120c --- /dev/null +++ b/docs/cli/daco_ports_list.md @@ -0,0 +1,37 @@ +## daco ports list + +List all ports in the OpenDPI spec + +### Synopsis + +List all ports defined in the OpenDPI spec. +Displays port names, schema types, descriptions, and connection information. + +``` +daco ports list [flags] +``` + +### Examples + +``` + # List ports in table format + daco ports list + + # List ports as JSON + daco ports list -o json + + # List ports as YAML + daco ports list -o yaml +``` + +### Options + +``` + -h, --help help for list + -o, --output string Output format (table, json, yaml) (default "table") +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_remove.md b/docs/cli/daco_ports_remove.md new file mode 100644 index 0000000..b2dc274 --- /dev/null +++ b/docs/cli/daco_ports_remove.md @@ -0,0 +1,38 @@ +## daco ports remove + +Remove a port from the OpenDPI spec + +### Synopsis + +Remove a port from the OpenDPI spec. +If no port name is provided, an interactive selection prompt is shown. +Requires confirmation unless --force is specified. + +``` +daco ports remove [PORT_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco ports remove + + # Remove with confirmation prompt + daco ports remove user_events + + # Remove without confirmation + daco ports remove user_events --force +``` + +### Options + +``` + -f, --force Skip confirmation prompt + -h, --help help for remove +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_translate.md b/docs/cli/daco_ports_translate.md new file mode 100644 index 0000000..c7648f6 --- /dev/null +++ b/docs/cli/daco_ports_translate.md @@ -0,0 +1,41 @@ +## daco ports translate + +Translate a port schema to a target format + +### Synopsis + +Translate a port schema to a target format. + +Available formats: spark-sql, pyspark, gotypes, avro, databricks-pyspark, pydantic, databricks-sql, protobuf, python, scala, spark-scala, databricks-scala + +``` +daco ports translate [flags] +``` + +### Examples + +``` + # Interactive mode + daco ports translate + + # Translate specific port + daco ports translate --name my-port --format pyspark --output schema.py + + # Translate to a custom directory (also sets package name for Go/Protobuf/Scala) + daco ports translate --format go --output-dir models +``` + +### Options + +``` + -f, --format string Output format (scala, spark-scala, databricks-scala, python, gotypes, avro, databricks-pyspark, pydantic, databricks-sql, protobuf, spark-sql, pyspark) + -h, --help help for translate + -n, --name string Port name (translates all if not specified) + -o, --output string Output file path (only valid when translating a single port) + -d, --output-dir string Output directory (also used as package name for Go/Protobuf/Scala) (default "schemas") +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/go.mod b/go.mod index ae776d1..863fd54 100644 --- a/go.mod +++ b/go.mod @@ -22,6 +22,7 @@ require ( github.com/charmbracelet/x/cellbuf v0.0.13 // indirect github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect github.com/charmbracelet/x/term v0.2.1 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect github.com/davecgh/go-spew v1.1.1 // indirect github.com/dustin/go-humanize v1.0.1 // indirect github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect @@ -36,8 +37,10 @@ require ( github.com/muesli/termenv v0.16.0 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect github.com/rivo/uniseg v0.4.7 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/spf13/pflag v1.0.9 // indirect github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect + go.yaml.in/yaml/v3 v3.0.4 // indirect golang.org/x/sync v0.15.0 // indirect golang.org/x/sys v0.33.0 // indirect golang.org/x/text v0.23.0 // indirect diff --git a/go.sum b/go.sum index 55e21f6..10417d1 100644 --- a/go.sum +++ b/go.sum @@ -36,6 +36,7 @@ github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8 github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo= github.com/charmbracelet/x/xpty v0.1.2 h1:Pqmu4TEJ8KeA9uSkISKMU3f+C1F6OGBn8ABuGlqCbtI= github.com/charmbracelet/x/xpty v0.1.2/go.mod h1:XK2Z0id5rtLWcpeNiMYBccNNBrP2IJnzHI0Lq13Xzq4= +github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s= github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE= @@ -72,6 +73,7 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ= github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= @@ -81,6 +83,7 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM= +go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc= go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI= golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo= diff --git a/internal/commands/register.go b/internal/commands/register.go index 066ff46..8d29976 100644 --- a/internal/commands/register.go +++ b/internal/commands/register.go @@ -14,14 +14,22 @@ import ( // NewRootCmd creates and returns the root command for the CLI. func NewRootCmd(translators translate.Register) *cobra.Command { rootCmd := &cobra.Command{ - Use: "daco", + Use: "daco", + Short: "Data product CLI tool", + Long: `daco is a CLI for defining, managing, and translating data product specifications +using the OpenDPI standard. It supports managing ports (with JSON schemas), +infrastructure connections, and translating schemas to formats such as PySpark, +Avro, Protobuf, Go types, and more.`, Version: version.Short(), } rootCmd.SetVersionTemplate(version.Info() + "\n") portsCmd := &cobra.Command{ - Use: "ports", - Short: "Manage data product ports", + Use: "ports", + Short: "Manage data product ports", + Long: `Manage data product ports defined in the OpenDPI spec. Ports represent +data interfaces (input or output) with associated JSON schemas and connections. +Use subcommands to add, list, describe, remove, or translate port schemas.`, PersistentPreRunE: session.PreRunLoad, } portsCmd.AddCommand( @@ -32,8 +40,11 @@ func NewRootCmd(translators translate.Register) *cobra.Command { newPortsTranslateCmd(translators)) connsCmd := &cobra.Command{ - Use: "connections", - Short: "Manage data product connections", + Use: "connections", + Short: "Manage data product connections", + Long: `Manage infrastructure connections defined in the OpenDPI spec. Connections +describe how to reach external systems (Kafka, PostgreSQL, S3, HTTP, etc.) +and are referenced by ports. Use subcommands to add, list, describe, or remove connections.`, PersistentPreRunE: session.PreRunLoad, } connsCmd.AddCommand( From fdc02bfeb69092680046138b22a62ecf3777e208 Mon Sep 17 00:00:00 2001 From: Gudmundur Orri Palsson Date: Sat, 31 Jan 2026 12:14:10 +0100 Subject: [PATCH 2/4] feat: add LLM-friendly CLI documentation Add cobra/doc-based markdown generator and enrich command descriptions for better LLM consumption. Fix spark-scala translator wiring. Co-Authored-By: Claude Opus 4.5 --- .gitignore | 1 + cmd/daco/internal/app.go | 3 +- cmd/gendocs/main.go | 68 +++++++++++++++++++++++++++ docs/cli/daco.md | 23 +++++++++ docs/cli/daco_connections.md | 24 ++++++++++ docs/cli/daco_connections_add.md | 37 +++++++++++++++ docs/cli/daco_connections_describe.md | 39 +++++++++++++++ docs/cli/daco_connections_list.md | 36 ++++++++++++++ docs/cli/daco_connections_remove.md | 36 ++++++++++++++ docs/cli/daco_init.md | 41 ++++++++++++++++ docs/cli/daco_ports.md | 25 ++++++++++ docs/cli/daco_ports_add.md | 41 ++++++++++++++++ docs/cli/daco_ports_describe.md | 39 +++++++++++++++ docs/cli/daco_ports_list.md | 37 +++++++++++++++ docs/cli/daco_ports_remove.md | 38 +++++++++++++++ docs/cli/daco_ports_translate.md | 41 ++++++++++++++++ go.mod | 3 ++ go.sum | 3 ++ internal/commands/register.go | 21 +++++++-- 19 files changed, 550 insertions(+), 6 deletions(-) create mode 100644 cmd/gendocs/main.go create mode 100644 docs/cli/daco.md create mode 100644 docs/cli/daco_connections.md create mode 100644 docs/cli/daco_connections_add.md create mode 100644 docs/cli/daco_connections_describe.md create mode 100644 docs/cli/daco_connections_list.md create mode 100644 docs/cli/daco_connections_remove.md create mode 100644 docs/cli/daco_init.md create mode 100644 docs/cli/daco_ports.md create mode 100644 docs/cli/daco_ports_add.md create mode 100644 docs/cli/daco_ports_describe.md create mode 100644 docs/cli/daco_ports_list.md create mode 100644 docs/cli/daco_ports_remove.md create mode 100644 docs/cli/daco_ports_translate.md diff --git a/.gitignore b/.gitignore index aeb6bdc..f3b8791 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ # Binaries bin/ +gendocs *.exe *.exe~ *.dll diff --git a/cmd/daco/internal/app.go b/cmd/daco/internal/app.go index 1eb1c5b..3770b3c 100644 --- a/cmd/daco/internal/app.go +++ b/cmd/daco/internal/app.go @@ -19,6 +19,7 @@ import ( "github.com/dacolabs/cli/internal/translate/pyspark" "github.com/dacolabs/cli/internal/translate/python" "github.com/dacolabs/cli/internal/translate/scala" + "github.com/dacolabs/cli/internal/translate/sparkscala" "github.com/dacolabs/cli/internal/translate/sparksql" ) @@ -32,7 +33,7 @@ func registerTranslators() translate.Register { translators["python"] = &python.Translator{} translators["databricks-sql"] = &databrickssql.Translator{} translators["scala"] = &scala.Translator{} - translators["spark-scala"] = &pyspark.Translator{} + translators["spark-scala"] = &sparkscala.Translator{} translators["databricks-scala"] = &databricksscala.Translator{} translators["protobuf"] = &protobuf.Translator{} translators["spark-sql"] = &sparksql.Translator{} diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go new file mode 100644 index 0000000..cfe50c9 --- /dev/null +++ b/cmd/gendocs/main.go @@ -0,0 +1,68 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2026 Daco Labs + +// Command gendocs generates LLM-friendly markdown documentation for the daco CLI. +// +// Usage: +// +// go run ./cmd/gendocs [output-dir] +// +// Default output directory is ./docs/cli. +package main + +import ( + "fmt" + "os" + + "github.com/dacolabs/cli/internal/commands" + "github.com/dacolabs/cli/internal/translate" + "github.com/dacolabs/cli/internal/translate/avro" + "github.com/dacolabs/cli/internal/translate/databrickspyspark" + "github.com/dacolabs/cli/internal/translate/databricksscala" + "github.com/dacolabs/cli/internal/translate/databrickssql" + "github.com/dacolabs/cli/internal/translate/gotypes" + "github.com/dacolabs/cli/internal/translate/protobuf" + "github.com/dacolabs/cli/internal/translate/pydantic" + "github.com/dacolabs/cli/internal/translate/pyspark" + "github.com/dacolabs/cli/internal/translate/python" + "github.com/dacolabs/cli/internal/translate/scala" + "github.com/dacolabs/cli/internal/translate/sparkscala" + "github.com/dacolabs/cli/internal/translate/sparksql" + "github.com/spf13/cobra/doc" +) + +func main() { + dir := "./docs/cli" + if len(os.Args) > 1 { + dir = os.Args[1] + } + + translators := make(translate.Register) + translators["pyspark"] = &pyspark.Translator{} + translators["gotypes"] = &gotypes.Translator{} + translators["avro"] = &avro.Translator{} + translators["databricks-pyspark"] = &databrickspyspark.Translator{} + translators["pydantic"] = &pydantic.Translator{} + translators["python"] = &python.Translator{} + translators["databricks-sql"] = &databrickssql.Translator{} + translators["scala"] = &scala.Translator{} + translators["spark-scala"] = &sparkscala.Translator{} + translators["databricks-scala"] = &databricksscala.Translator{} + translators["protobuf"] = &protobuf.Translator{} + translators["spark-sql"] = &sparksql.Translator{} + + rootCmd := commands.NewRootCmd(translators) + rootCmd.DisableAutoGenTag = true + + if err := os.MkdirAll(dir, 0o750); err != nil { + fmt.Fprintf(os.Stderr, "error creating output dir: %v\n", err) + os.Exit(1) + } + + if err := doc.GenMarkdownTree(rootCmd, dir); err != nil { + fmt.Fprintf(os.Stderr, "error generating docs: %v\n", err) + os.Exit(1) + } + + fmt.Printf("Documentation generated in %s\n", dir) +} diff --git a/docs/cli/daco.md b/docs/cli/daco.md new file mode 100644 index 0000000..b5e8385 --- /dev/null +++ b/docs/cli/daco.md @@ -0,0 +1,23 @@ +## daco + +Data product CLI tool + +### Synopsis + +daco is a CLI for defining, managing, and translating data product specifications +using the OpenDPI standard. It supports managing ports (with JSON schemas), +infrastructure connections, and translating schemas to formats such as PySpark, +Avro, Protobuf, Go types, and more. + +### Options + +``` + -h, --help help for daco +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections +* [daco init](daco_init.md) - Initialize a new daco project +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_connections.md b/docs/cli/daco_connections.md new file mode 100644 index 0000000..ad9f2e2 --- /dev/null +++ b/docs/cli/daco_connections.md @@ -0,0 +1,24 @@ +## daco connections + +Manage data product connections + +### Synopsis + +Manage infrastructure connections defined in the OpenDPI spec. Connections +describe how to reach external systems (Kafka, PostgreSQL, S3, HTTP, etc.) +and are referenced by ports. Use subcommands to add, list, describe, or remove connections. + +### Options + +``` + -h, --help help for connections +``` + +### SEE ALSO + +* [daco](daco.md) - Data product CLI tool +* [daco connections add](daco_connections_add.md) - Add a new connection to the OpenDPI spec +* [daco connections describe](daco_connections_describe.md) - Show detailed information about a connection +* [daco connections list](daco_connections_list.md) - List all connections in the OpenDPI spec +* [daco connections remove](daco_connections_remove.md) - Remove a connection from the OpenDPI spec + diff --git a/docs/cli/daco_connections_add.md b/docs/cli/daco_connections_add.md new file mode 100644 index 0000000..23468c0 --- /dev/null +++ b/docs/cli/daco_connections_add.md @@ -0,0 +1,37 @@ +## daco connections add + +Add a new connection to the OpenDPI spec + +### Synopsis + +Add a new infrastructure connection to the OpenDPI spec. + +``` +daco connections add [flags] +``` + +### Examples + +``` + # Interactive mode + daco connections add + + # Non-interactive + daco connections add -n kafka_prod -p kafka --host broker:9092 --non-interactive +``` + +### Options + +``` + -d, --description string Description + -h, --help help for add + --host string Host/endpoint + -n, --name string Connection name + --non-interactive Run without prompts + -p, --protocol string Protocol (kafka, postgresql, mysql, s3, http, etc.) +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_connections_describe.md b/docs/cli/daco_connections_describe.md new file mode 100644 index 0000000..559e083 --- /dev/null +++ b/docs/cli/daco_connections_describe.md @@ -0,0 +1,39 @@ +## daco connections describe + +Show detailed information about a connection + +### Synopsis + +Display complete connection details including which ports use it. If no connection name is provided, an interactive selection prompt is shown. + +``` +daco connections describe [CONNECTION_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco connections describe + + # Show connection details + daco connections describe kafka_prod + + # Show as JSON + daco connections describe kafka_prod -o json + + # Show as YAML + daco connections describe kafka_prod -o yaml +``` + +### Options + +``` + -h, --help help for describe + -o, --output string Output format (text, json, yaml) (default "text") +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_connections_list.md b/docs/cli/daco_connections_list.md new file mode 100644 index 0000000..26b4bf6 --- /dev/null +++ b/docs/cli/daco_connections_list.md @@ -0,0 +1,36 @@ +## daco connections list + +List all connections in the OpenDPI spec + +### Synopsis + +List all connections defined in the OpenDPI spec with their protocols and hosts. + +``` +daco connections list [flags] +``` + +### Examples + +``` + # List connections in table format + daco connections list + + # List connections as JSON + daco connections list -o json + + # List connections as YAML + daco connections list -o yaml +``` + +### Options + +``` + -h, --help help for list + -o, --output string Output format (table, json, yaml) (default "table") +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_connections_remove.md b/docs/cli/daco_connections_remove.md new file mode 100644 index 0000000..1e29ce0 --- /dev/null +++ b/docs/cli/daco_connections_remove.md @@ -0,0 +1,36 @@ +## daco connections remove + +Remove a connection from the OpenDPI spec + +### Synopsis + +Remove a connection from the OpenDPI spec. Cannot remove connections that are in use by ports. If no connection name is provided, an interactive selection prompt is shown. + +``` +daco connections remove [CONNECTION_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco connections remove + + # Remove with confirmation + daco connections remove unused_conn + + # Remove without confirmation + daco connections remove unused_conn --force +``` + +### Options + +``` + -f, --force Skip confirmation prompt + -h, --help help for remove +``` + +### SEE ALSO + +* [daco connections](daco_connections.md) - Manage data product connections + diff --git a/docs/cli/daco_init.md b/docs/cli/daco_init.md new file mode 100644 index 0000000..edb0d31 --- /dev/null +++ b/docs/cli/daco_init.md @@ -0,0 +1,41 @@ +## daco init + +Initialize a new daco project + +### Synopsis + +Initialize a new daco project with a daco.yaml configuration file. +Can create a new spec, use an existing one, or extend a parent config. + +``` +daco init [flags] +``` + +### Examples + +``` + # Interactive mode + daco init + + # Non-interactive + daco init --name "my-product" --non-interactive + daco init --extends ../daco.yaml --non-interactive +``` + +### Options + +``` + -e, --extends string Path to parent daco.yaml + -f, --format string Spec format (yaml or json) (default "yaml") + -h, --help help for init + -n, --name string Project name + --non-interactive Run without prompts (requires --name or --extends) + -p, --path string Path to spec folder (default "./spec") + -s, --schema-organization string Schema organization (modular, components, or inline) (default "modular") + -v, --version string Initial spec version (default "1.0.0") +``` + +### SEE ALSO + +* [daco](daco.md) - Data product CLI tool + diff --git a/docs/cli/daco_ports.md b/docs/cli/daco_ports.md new file mode 100644 index 0000000..ca487db --- /dev/null +++ b/docs/cli/daco_ports.md @@ -0,0 +1,25 @@ +## daco ports + +Manage data product ports + +### Synopsis + +Manage data product ports defined in the OpenDPI spec. Ports represent +data interfaces (input or output) with associated JSON schemas and connections. +Use subcommands to add, list, describe, remove, or translate port schemas. + +### Options + +``` + -h, --help help for ports +``` + +### SEE ALSO + +* [daco](daco.md) - Data product CLI tool +* [daco ports add](daco_ports_add.md) - Add a new port to the OpenDPI spec +* [daco ports describe](daco_ports_describe.md) - Show detailed information about a port +* [daco ports list](daco_ports_list.md) - List all ports in the OpenDPI spec +* [daco ports remove](daco_ports_remove.md) - Remove a port from the OpenDPI spec +* [daco ports translate](daco_ports_translate.md) - Translate a port schema to a target format + diff --git a/docs/cli/daco_ports_add.md b/docs/cli/daco_ports_add.md new file mode 100644 index 0000000..43a8892 --- /dev/null +++ b/docs/cli/daco_ports_add.md @@ -0,0 +1,41 @@ +## daco ports add + +Add a new port to the OpenDPI spec + +### Synopsis + +Add a new port to the OpenDPI spec with schema and connection configuration. +Ports can have optional schemas (from file or created interactively) and +connections that define where data flows. + +``` +daco ports add [flags] +``` + +### Examples + +``` + # Interactive mode + daco ports add + + # Non-interactive with existing connection + daco ports add --name events --schema-file ./schemas/event.json \ + --connection kafka --location events_topic --non-interactive +``` + +### Options + +``` + -c, --connection string Connection name + -d, --description string Port description + -h, --help help for add + -l, --location string Location (table, topic, path, etc.) + -n, --name string Port name + --non-interactive Run without prompts + -s, --schema-file string Path to JSON schema file +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_describe.md b/docs/cli/daco_ports_describe.md new file mode 100644 index 0000000..7972e7e --- /dev/null +++ b/docs/cli/daco_ports_describe.md @@ -0,0 +1,39 @@ +## daco ports describe + +Show detailed information about a port + +### Synopsis + +Display complete port definition including schema and connections. If no port name is provided, an interactive selection prompt is shown. + +``` +daco ports describe [PORT_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco ports describe + + # Show port details in human-readable format + daco ports describe user_events + + # Show port details as JSON + daco ports describe user_events -o json + + # Show port details as YAML + daco ports describe user_events -o yaml +``` + +### Options + +``` + -h, --help help for describe + -o, --output string Output format (text, json, yaml) (default "text") +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_list.md b/docs/cli/daco_ports_list.md new file mode 100644 index 0000000..c2c120c --- /dev/null +++ b/docs/cli/daco_ports_list.md @@ -0,0 +1,37 @@ +## daco ports list + +List all ports in the OpenDPI spec + +### Synopsis + +List all ports defined in the OpenDPI spec. +Displays port names, schema types, descriptions, and connection information. + +``` +daco ports list [flags] +``` + +### Examples + +``` + # List ports in table format + daco ports list + + # List ports as JSON + daco ports list -o json + + # List ports as YAML + daco ports list -o yaml +``` + +### Options + +``` + -h, --help help for list + -o, --output string Output format (table, json, yaml) (default "table") +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_remove.md b/docs/cli/daco_ports_remove.md new file mode 100644 index 0000000..b2dc274 --- /dev/null +++ b/docs/cli/daco_ports_remove.md @@ -0,0 +1,38 @@ +## daco ports remove + +Remove a port from the OpenDPI spec + +### Synopsis + +Remove a port from the OpenDPI spec. +If no port name is provided, an interactive selection prompt is shown. +Requires confirmation unless --force is specified. + +``` +daco ports remove [PORT_NAME] [flags] +``` + +### Examples + +``` + # Interactive selection + daco ports remove + + # Remove with confirmation prompt + daco ports remove user_events + + # Remove without confirmation + daco ports remove user_events --force +``` + +### Options + +``` + -f, --force Skip confirmation prompt + -h, --help help for remove +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/docs/cli/daco_ports_translate.md b/docs/cli/daco_ports_translate.md new file mode 100644 index 0000000..c7648f6 --- /dev/null +++ b/docs/cli/daco_ports_translate.md @@ -0,0 +1,41 @@ +## daco ports translate + +Translate a port schema to a target format + +### Synopsis + +Translate a port schema to a target format. + +Available formats: spark-sql, pyspark, gotypes, avro, databricks-pyspark, pydantic, databricks-sql, protobuf, python, scala, spark-scala, databricks-scala + +``` +daco ports translate [flags] +``` + +### Examples + +``` + # Interactive mode + daco ports translate + + # Translate specific port + daco ports translate --name my-port --format pyspark --output schema.py + + # Translate to a custom directory (also sets package name for Go/Protobuf/Scala) + daco ports translate --format go --output-dir models +``` + +### Options + +``` + -f, --format string Output format (scala, spark-scala, databricks-scala, python, gotypes, avro, databricks-pyspark, pydantic, databricks-sql, protobuf, spark-sql, pyspark) + -h, --help help for translate + -n, --name string Port name (translates all if not specified) + -o, --output string Output file path (only valid when translating a single port) + -d, --output-dir string Output directory (also used as package name for Go/Protobuf/Scala) (default "schemas") +``` + +### SEE ALSO + +* [daco ports](daco_ports.md) - Manage data product ports + diff --git a/go.mod b/go.mod index ae776d1..863fd54 100644 --- a/go.mod +++ b/go.mod @@ -22,6 +22,7 @@ require ( github.com/charmbracelet/x/cellbuf v0.0.13 // indirect github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect github.com/charmbracelet/x/term v0.2.1 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect github.com/davecgh/go-spew v1.1.1 // indirect github.com/dustin/go-humanize v1.0.1 // indirect github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect @@ -36,8 +37,10 @@ require ( github.com/muesli/termenv v0.16.0 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect github.com/rivo/uniseg v0.4.7 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/spf13/pflag v1.0.9 // indirect github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect + go.yaml.in/yaml/v3 v3.0.4 // indirect golang.org/x/sync v0.15.0 // indirect golang.org/x/sys v0.33.0 // indirect golang.org/x/text v0.23.0 // indirect diff --git a/go.sum b/go.sum index 55e21f6..10417d1 100644 --- a/go.sum +++ b/go.sum @@ -36,6 +36,7 @@ github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8 github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo= github.com/charmbracelet/x/xpty v0.1.2 h1:Pqmu4TEJ8KeA9uSkISKMU3f+C1F6OGBn8ABuGlqCbtI= github.com/charmbracelet/x/xpty v0.1.2/go.mod h1:XK2Z0id5rtLWcpeNiMYBccNNBrP2IJnzHI0Lq13Xzq4= +github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s= github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE= @@ -72,6 +73,7 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ= github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= @@ -81,6 +83,7 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM= +go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc= go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI= golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo= diff --git a/internal/commands/register.go b/internal/commands/register.go index 066ff46..8d29976 100644 --- a/internal/commands/register.go +++ b/internal/commands/register.go @@ -14,14 +14,22 @@ import ( // NewRootCmd creates and returns the root command for the CLI. func NewRootCmd(translators translate.Register) *cobra.Command { rootCmd := &cobra.Command{ - Use: "daco", + Use: "daco", + Short: "Data product CLI tool", + Long: `daco is a CLI for defining, managing, and translating data product specifications +using the OpenDPI standard. It supports managing ports (with JSON schemas), +infrastructure connections, and translating schemas to formats such as PySpark, +Avro, Protobuf, Go types, and more.`, Version: version.Short(), } rootCmd.SetVersionTemplate(version.Info() + "\n") portsCmd := &cobra.Command{ - Use: "ports", - Short: "Manage data product ports", + Use: "ports", + Short: "Manage data product ports", + Long: `Manage data product ports defined in the OpenDPI spec. Ports represent +data interfaces (input or output) with associated JSON schemas and connections. +Use subcommands to add, list, describe, remove, or translate port schemas.`, PersistentPreRunE: session.PreRunLoad, } portsCmd.AddCommand( @@ -32,8 +40,11 @@ func NewRootCmd(translators translate.Register) *cobra.Command { newPortsTranslateCmd(translators)) connsCmd := &cobra.Command{ - Use: "connections", - Short: "Manage data product connections", + Use: "connections", + Short: "Manage data product connections", + Long: `Manage infrastructure connections defined in the OpenDPI spec. Connections +describe how to reach external systems (Kafka, PostgreSQL, S3, HTTP, etc.) +and are referenced by ports. Use subcommands to add, list, describe, or remove connections.`, PersistentPreRunE: session.PreRunLoad, } connsCmd.AddCommand( From ea9ceb4797a0e316344263218b1830e665aff2a0 Mon Sep 17 00:00:00 2001 From: Gudmundur Orri Palsson Date: Sat, 31 Jan 2026 12:15:52 +0100 Subject: [PATCH 3/4] Fix conflict --- cmd/gendocs/main.go | 5 ----- 1 file changed, 5 deletions(-) diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go index 7121bf2..cfe50c9 100644 --- a/cmd/gendocs/main.go +++ b/cmd/gendocs/main.go @@ -26,14 +26,9 @@ import ( "github.com/dacolabs/cli/internal/translate/pyspark" "github.com/dacolabs/cli/internal/translate/python" "github.com/dacolabs/cli/internal/translate/scala" -<<<<<<< HEAD "github.com/dacolabs/cli/internal/translate/sparkscala" "github.com/dacolabs/cli/internal/translate/sparksql" "github.com/spf13/cobra/doc" -======= - "github.com/dacolabs/cli/internal/translate/sparksql" - doc "github.com/spf13/cobra/doc" ->>>>>>> 45f0b393029713400ba4e6f2226ec3201b2bb3e5 ) func main() { From 66878be6d83488a05746b45a439389e416307437 Mon Sep 17 00:00:00 2001 From: Gudmundur Orri Palsson Date: Sat, 31 Jan 2026 12:39:42 +0100 Subject: [PATCH 4/4] go is called gotypes --- docs/cli/daco_ports_translate.md | 6 +++--- internal/commands/ports_translate.go | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cli/daco_ports_translate.md b/docs/cli/daco_ports_translate.md index c7648f6..00ef6e3 100644 --- a/docs/cli/daco_ports_translate.md +++ b/docs/cli/daco_ports_translate.md @@ -6,7 +6,7 @@ Translate a port schema to a target format Translate a port schema to a target format. -Available formats: spark-sql, pyspark, gotypes, avro, databricks-pyspark, pydantic, databricks-sql, protobuf, python, scala, spark-scala, databricks-scala +Available formats: avro, databricks-sql, spark-scala, databricks-scala, spark-sql, pyspark, gotypes, databricks-pyspark, pydantic, python, scala, protobuf ``` daco ports translate [flags] @@ -22,13 +22,13 @@ daco ports translate [flags] daco ports translate --name my-port --format pyspark --output schema.py # Translate to a custom directory (also sets package name for Go/Protobuf/Scala) - daco ports translate --format go --output-dir models + daco ports translate --format gotypes --output-dir models ``` ### Options ``` - -f, --format string Output format (scala, spark-scala, databricks-scala, python, gotypes, avro, databricks-pyspark, pydantic, databricks-sql, protobuf, spark-sql, pyspark) + -f, --format string Output format (databricks-scala, spark-sql, avro, databricks-sql, spark-scala, pydantic, python, scala, protobuf, pyspark, gotypes, databricks-pyspark) -h, --help help for translate -n, --name string Port name (translates all if not specified) -o, --output string Output file path (only valid when translating a single port) diff --git a/internal/commands/ports_translate.go b/internal/commands/ports_translate.go index 5a49d82..166b00d 100644 --- a/internal/commands/ports_translate.go +++ b/internal/commands/ports_translate.go @@ -43,7 +43,7 @@ Available formats: %s`, strings.Join(translators.Available(), ", ")), daco ports translate --name my-port --format pyspark --output schema.py # Translate to a custom directory (also sets package name for Go/Protobuf/Scala) - daco ports translate --format go --output-dir models`, + daco ports translate --format gotypes --output-dir models`, RunE: func(cmd *cobra.Command, args []string) error { return runPortsTranslate(cmd, translators, opts) },