{"id":18310907,"url":"https://github.com/jimschubert/venom","last_synced_at":"2025-04-09T12:10:36.065Z","repository":{"id":163769936,"uuid":"637602162","full_name":"jimschubert/venom","owner":"jimschubert","description":"A documentation command for your CLIs built on top of cobra.","archived":false,"fork":false,"pushed_at":"2023-05-21T15:18:43.000Z","size":91,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-15T05:46:20.657Z","etag":null,"topics":["cobra-cli","go","golang"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/jimschubert/venom","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimschubert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"jimschubert","patreon":"jimschubert"}},"created_at":"2023-05-08T02:40:23.000Z","updated_at":"2023-05-09T02:37:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"9bcc8a17-9043-43b4-8bc8-02f67eed4c19","html_url":"https://github.com/jimschubert/venom","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fvenom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fvenom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fvenom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimschubert%2Fvenom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimschubert","download_url":"https://codeload.github.com/jimschubert/venom/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036066,"owners_count":21037092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cobra-cli","go","golang"],"created_at":"2024-11-05T16:15:50.984Z","updated_at":"2025-04-09T12:10:36.045Z","avatar_url":"https://github.com/jimschubert.png","language":"Go","funding_links":["https://github.com/sponsors/jimschubert","https://patreon.com/jimschubert"],"categories":[],"sub_categories":[],"readme":"# venom\n\nAll you need to know about cobra commands. Generate documentation in a variety of formats, similar to what's available in Cobra but with some simplifications and fixes.\n\n![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/jimschubert/venom?color=blue\u0026sort=semver)\n![Go Version](https://img.shields.io/github/go-mod/go-version/jimschubert/venom)\n[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue)](./LICENSE)  \n[![build](https://github.com/jimschubert/venom/actions/workflows/build.yml/badge.svg)](https://github.com/jimschubert/venom/actions/workflows/build.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/jimschubert/venom)](https://goreportcard.com/report/github.com/jimschubert/venom)\n\n## Features\n\n* Documentation output for Markdown, YAML, JSON, reStructuredText\n* Customizable YAML and JSON marshaling\n* User-defined templating for Markdown and reStructuredText\n\n## TODO\n\n* Manpage support\n\n## Install\n\n```\ngo get -u github.com/jimschubert/venom\n```\n\n## Usage\n\nVenom can be used either to add a documentation command as a child to another command, or to perform ad hoc writes of documentation directly.\n\nThe options, constructed via `venom.NewOptions()`, are the same for both use cases. These options follow the builder pattern to make available options easily discoverable.\n\nAll defined formats will be generated into the output directory, which defaults to `docs` and is configurable.\n\n### As a child command\n\nFirst, initialize `venom.NewOptions()`. \nNext, initialize venom by passing your root command the above options. For example:\n\n```go\nfunc init() {\n\topts := venom.NewOptions().\n\t\tWithFormats(venom.Yaml | venom.Json | venom.Markdown).\n\t\tWithShowHiddenCommands()\n\tcobra.CheckErr(venom.Initialize(rootCmd, opts))\n}\n```\n\nHere is a full example of generating only markdown: \n\n```go\npackage main\n\nimport (\n\t\"github.com/jimschubert/venom\"\n\t\"github.com/spf13/cobra\"\n)\n\nvar rootCmd = \u0026cobra.Command{\n\tUse:   \"example\",\n\tShort: \"root command\",\n\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\treturn cmd.Help()\n\t},\n}\n\nfunc init() {\n\trootCmd.Flags().BoolP(\"toggle\", \"t\", false, \"Help message for toggle\")\n\topts := venom.NewOptions().WithFormats(venom.Markdown)\n\tcobra.CheckErr(venom.Initialize(rootCmd, opts))\n}\n\nfunc main() {\n\trootCmd.Execute()\n}\n```\n\nIf you compile and run this application, you won't see a `docs` command because it's hidden. Invoke the hidden command (e.g. `example docs`) to output the documentation. \n\nThe `docs` subcommand which venom creates will allow the user to specify a subset of the allowed formats, to define a new output directory, and to show all hidden commands.\n\n```\nUsage:\n  example docs [flags]\n\nFlags:\n      --formats strings   A comma-separated list of formats to output. Allowed: [yaml,markdown] (default [yaml,markdown])\n  -h, --help              help for docs\n      --out-dir string    The target output directory (default \"docs\")\n      --show-hidden       Also show hidden commands\n\n```\n\n### Via Write\n\nSuppose you want to wire this functionality up into an existing documentation command, or maybe you want to generate on \nbuild via a go generator utility command. You can do this by invoking the `Write` command directly.\n\nFor example:\n\n```go\ndocs := venom.NewDocumentation(rootCmd, venom.NewOptions().WithFormats(venom.Markdown))\nif err := venom.Write(docs)); err != nil {\n\t// do something with err\n}\n```\n\n## Custom Templates\n\nYou can provide your own templates if the built-in templates don't suit your needs. The built-in templates are intended \nto match as closely as possible with those output by Cobra's built-in command. But, there are cases where these aren't desirable. For instance:\n\n* markdown-driven doc sites like Docusaurus generate first-level headers if missing in markdown\n* you want front-matter for an extended markdown system like Jekyll\n* you want to do something unexpected like output Asciidoc by tweaking the Markdown templates\n* you simply don't like the formatting\n\nTo provide custom templates, you just need to make sure your files are named exactly the same as they are under [./templates](./templates) in this repository.\nThen, pass an implementation of `fs.FS` to our options. You can use go embed to read an entire directory called `your_directory` like this:\n\n```\n//go:embed your_directory/*.tmpl\nvar templates embed.FS\n\nfunc init() {\n\topts := venom.NewOptions().WithCustomTemplates(templates)\n\tcobra.CheckErr(venom.Initialize(rootCmd, opts))\n}\n```\n\nAnd as long as you have both `markdown_command.tmpl` and `markdown_index.tmpl` defined under `your_directory`, you're all set!\n\nThe types definitions which are bound to these templates can be found in [./types.go](./types.go).\n\nCommand templates will be bound to a data structure matching:\n\n```go\nstruct {\n    Command\n    Doc Documentation\n}\n```\n\nThe embedded `Command` allows you to interact with the command's fields directly at the top level of the template. The `Doc` \nfield is the full documentation, providing you access to the root command and all child commands.\n\nIndex templates will be bound to the `Documentation` structure directly.\n\n**NOTE** Not all output formats are template driven. Be sure to review [./templates](./templates).\n\n## Build/Test\n\n```shell\ngo test -v -race -cover ./...\n```\n\n## License\n\nThis project is [licensed](./LICENSE) under Apache 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimschubert%2Fvenom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimschubert%2Fvenom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimschubert%2Fvenom/lists"}