{"id":37759241,"url":"https://github.com/cs3org/cato","last_synced_at":"2026-01-16T14:34:30.051Z","repository":{"id":109827276,"uuid":"269687178","full_name":"cs3org/cato","owner":"cs3org","description":"Automated configuration documentation library for Go Projects.","archived":false,"fork":false,"pushed_at":"2020-08-28T12:56:08.000Z","size":35,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-06-18T21:39:46.543Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/cs3org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2020-06-05T15:37:17.000Z","updated_at":"2023-11-02T12:29:35.000Z","dependencies_parsed_at":"2023-05-26T21:45:25.040Z","dependency_job_id":null,"html_url":"https://github.com/cs3org/cato","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cs3org/cato","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cs3org%2Fcato","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cs3org%2Fcato/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cs3org%2Fcato/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cs3org%2Fcato/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cs3org","download_url":"https://codeload.github.com/cs3org/cato/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cs3org%2Fcato/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-16T14:34:29.951Z","updated_at":"2026-01-16T14:34:30.039Z","avatar_url":"https://github.com/cs3org.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cato\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Go](https://github.com/cs3org/cato/workflows/Go/badge.svg)](https://github.com/cs3org/cato/actions)\n\nCato is an automated documentation generation library for Go Projects. Through the use of custom tags for struct fields, Cato can extract information such as\n- data type of the fields\n- default values\n- description through comments or tags\n- online references to point to\n\nAfter this extraction, this data can be exported through multiple interfaces, such as HTML and markdown.\n\nThe motivation for creating this library was to save developers from the trouble of describing configuration details separately for the end-users. With Cato, it can be generated on the fly by adding minimal info through custom tags.\n\n\n## Installation\n\n`go get github.com/cs3org/cato`\n\n\n## Usage\n\nSome examples can be found in [cato_html_test.go](cato_html_test.go) and [cato_markdown_test.go](cato_markdown_test.go) which act on [filesystem.go](examples/filesystem.go). The general usage is:\n\n```go\nimport (\n\t\"github.com/cs3org/cato\"\n\t\"github.com/cs3org/cato/resources\"\n)\n\nfunc main() {\n\trootPath := \"examples/\"\n\tconf := \u0026resources.CatoConfig{\n\t\tDriver: \"markdown\",\n\t\tDriverConfig: map[string]map[string]interface{}{\n\t\t\t\"markdown\": map[string]interface{}{\n\t\t\t\t\"ReferenceBase\": \"https://github.com/cs3org/cato/tree/master/examples\",\n\t\t\t},\n\t\t},\n\t}\n\n\tif _, err := cato.GenerateDocumentation(rootPath, conf); err != nil {\n\t\tlog.Error(err)\n\t}\n}\n```\n\nWe've integrated Cato with [Reva](https://github.com/cs3org/reva/) using a make [rule](https://github.com/cs3org/reva/blob/master/tools/generate-documentation/main.go) with a custom driver, where it's being used in [production](https://reva.link/docs/config/grpc/services/storageprovider/).\n\n## Workflow\n\n### Extraction\n\nCato works by generating the syntax tree for the go files using the [parser](https://golang.org/pkg/go/parser/) and [ast](https://golang.org/pkg/go/ast/) packages. It then inspects the tree to find structs with fields possessing a custom tag (the default is `docs`), and extracts details about those into the `FieldInfo` struct.\n\nA maximum of three values, separated by semicolons can be defined in these custom tags. The expected order of these values is:\n1. The name of the field as it should appear in the docs. If this is not specified, it looks for a few commonly used tags, namely `xml`, `mapstructure` and `json`, to pick up the field name from. If none of these are found, it uses the actual name of the field.\n2. The default value which is used for that particular field if it is not specified by the user. This makes it really convenient for end users reading the documentation to understand the configuration specifics.\n3. A description of the field. If no description is provided, Cato reads the comments provided with the field.\n\nAs an example, the `FileSystem` struct defined below lists the various ways in which tags can be defined.\n\n```go\ntype FileSystem struct {\n\n\t// docs:\"field_name;default_value;description\"\n\tCacheDirectory     string   `docs:\"cache_directory;/var/tmp/;Path of cache directory\"`\n\n\t// docs:\"default_value;description\" with json tag\n\tEnableLogging      bool     `json:\"enable_logging\" docs:\"false;Whether to enable logging\"`\n\n\t// docs:\"default_value;description\"\n\tAvailableChecksums []string `docs:\"[adler, rabin];The list of checksums provided by the file system\"`\n\n\t// docs:\"default_value\" with comment\n\t// Configs for various metadata drivers\n\tDriverConfig map[string]map[string]interface{} `docs:\"{json:{encoding: UTF8}, xml:{encoding: ASCII}}\"`\n}\n```\n\n### Exporters\n\nThis extracted information can be exported through multiple interfaces including markdown and HTML. If paths for the the documentation files are specified, the files are created there, otherwise they are exported in the same directory as the go file. If a reference address is provided, a pointer to the line numbers in a remotely hosted repo is also added for each of the fields.\n\n\n## License\n\nCato is distributed under the [Apache 2.0 license](https://github.com/cs3org/cato/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcs3org%2Fcato","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcs3org%2Fcato","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcs3org%2Fcato/lists"}