Automated configuration documentation library for Go Projects.

Cato

License Go

Cato is an automated documentation generation library for Go Projects. Through the use of custom tags for struct fields, Cato can extract information such as

  • data type of the fields
  • default values
  • description through comments or tags
  • online references to point to

After this extraction, this data can be exported through multiple interfaces, such as HTML and markdown.

The 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.

Installation

go get github.com/cs3org/cato

Usage

Some examples can be found in cato_html_test.go and cato_markdown_test.go which act on filesystem.go. The general usage is:

import (
	"github.com/cs3org/cato"
	"github.com/cs3org/cato/resources"
)

func main() {
	rootPath := "examples/"
	conf := &resources.CatoConfig{
		Driver: "markdown",
		DriverConfig: map[string]map[string]interface{}{
			"markdown": map[string]interface{}{
				"ReferenceBase": "https://github.com/cs3org/cato/tree/master/examples",
			},
		},
	}

	if _, err := cato.GenerateDocumentation(rootPath, conf); err != nil {
		log.Error(err)
	}
}

We've integrated Cato with Reva using a make rule with a custom driver, where it's being used in production.

Workflow

Extraction

Cato works by generating the syntax tree for the go files using the parser and 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.

A maximum of three values, separated by semicolons can be defined in these custom tags. The expected order of these values is:

  1. 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.
  2. 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.
  3. A description of the field. If no description is provided, Cato reads the comments provided with the field.

As an example, the FileSystem struct defined below lists the various ways in which tags can be defined.

type FileSystem struct {

	// docs:"field_name;default_value;description"
	CacheDirectory     string   `docs:"cache_directory;/var/tmp/;Path of cache directory"`

	// docs:"default_value;description" with json tag
	EnableLogging      bool     `json:"enable_logging" docs:"false;Whether to enable logging"`

	// docs:"default_value;description"
	AvailableChecksums []string `docs:"[adler, rabin];The list of checksums provided by the file system"`

	// docs:"default_value" with comment
	// Configs for various metadata drivers
	DriverConfig map[string]map[string]interface{} `docs:"{json:{encoding: UTF8}, xml:{encoding: ASCII}}"`
}

Exporters

This 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.

License

Cato is distributed under the Apache 2.0 license.

Owner
Similar Resources

Manage Go Versions/Projects/Dependencies

Manage Go Versions/Projects/Dependencies

rodent rodent is a shell (bash) application which: Manages multiple versions of Go. Allows you to test/build your projects against multiple Go release

Dec 13, 2022

Hermit manages isolated, self-bootstrapping sets of tools in software projects.

Hermit - uniform tooling for Linux and Mac Hermit installs tools for software projects in self-contained, isolated sets, so your team, your contributo

Jan 3, 2023

💻 A one-line installer for GitHub projects!

💻 A one-line installer for GitHub projects!

instl Instl is an installer that can install most GitHub projects on your system with a single command. Installation | Documentation | Contributing In

Jul 23, 2022

💻 A installer for GitHub projects!

💻 A installer for GitHub projects!

instl Instl is an installer that can install most GitHub projects on your system with a single command. Installation | Documentation | Contributing In

Nov 2, 2022

Hassle-free minimal CI/CD for git repositories with docker or docker-compose projects.

Hassle-free minimal CI/CD for git repositories with docker or docker-compose projects.

GIT-PIPE Hassle-free minimal CI/CD for git repos for docker-based projects. Features: zero configuration for repos by default automatic encrypted back

Sep 23, 2022

A set of tools for managing projects in github

Github-pm-groomer The goal of this project is to have a CLI which runs a set of different grooming stuff on github. Some features Normalize labels à l

Jan 5, 2022

A simple multi-layered config loader for Go. Made for smaller projects. No external dependencies.

gocfg ⚠️ Work in progress! A simple multi-layered config loader for Go. Made for smaller projects. No external dependencies. Example From main.go: //

Dec 26, 2021

Small tool to pull/push several projects in one go

gitTool Small tool to push and pull several projects in one go. Written in Go 1.17 by Roy Dybing Contact: location name/handle github: rDybing linked

Dec 28, 2021

Poc rsa - A simple golang scaffolding to help me to create new api projects or workers with golang on k8s

go-scaffold A simple golang scaffolding to help me to create new api projects or

Feb 3, 2022
Related tags
Clones github projects into ~/Projects/github/{org}/{repo}

Tidy clone Github cli extension (gh extension) to clone repos into ~/Projects/github/{org}/{repo} on the local filesystem Install gh extension install

Jan 19, 2022
Flux is a tool for keeping Kubernetes clusters in sync with sources of configuration, and automating updates to configuration when there is new code to deploy.
Flux is a tool for keeping Kubernetes clusters in sync with sources of configuration, and automating updates to configuration when there is new code to deploy.

Flux is a tool for keeping Kubernetes clusters in sync with sources of configuration (like Git repositories), and automating updates to configuration when there is new code to deploy.

Jan 8, 2023
A Golang library for testing infrastructure in automated ways.

Infratest Infratest is a Golang library that we hope makes testing your infrastructure using tests that are written in Golang easier to do. The genera

Nov 2, 2022
Gola is a Golang tool for automated scripting purpose

Gola Gola is a Golang tool for automated scripting purpose. How To Install You can find the install script here. Example Configuration commands: - n

Aug 12, 2022
Raspberry Pi Archlinux Automated Offline Installer with Wi-Fi. Windows, Mac and more features coming.
Raspberry Pi Archlinux Automated Offline Installer with Wi-Fi. Windows, Mac and more features coming.

Raspberry Pi Archlinux Automated Installer with Wi-Fi. Windows, Mac and more features coming. Download Go to releases page and download the zip file f

Nov 22, 2022
Mutagen Compose is a modified version of Docker Compose that offers automated integration with Mutagen.

Mutagen Compose Mutagen Compose is a (minimally) modified version of Docker Compose that offers automated integration with Mutagen. This allows you to

Dec 22, 2022
Automated-gke-cilium-networkpolicy-demo - Quickly provision and tear down a GKE cluster with Cilium enabled for working with Network Policy.

Automated GKE Network Policy Demo Before running the automation, make sure you have the correct variables in env-automation/group_vars/all.yaml. There

Jan 1, 2022
Rustpm - Process manager and automated updates for RustDedicated
Rustpm - Process manager and automated updates for RustDedicated

rustpm (WIP) Process manager for RustDedicated A drop in replacement for RustDed

Feb 15, 2022
Automated refactoring for Terraform

tfrefactor Automated refactoring for Terraform. Currently supports: Rename local / var / data / resource across all files in a config Move items or ca

Oct 21, 2022
Automated Arch Linux (Written in Go)
Automated Arch Linux (Written in Go)

ShobuArch -- Automated Arch Linux Tools (Written in Go) Have you ever wanted to use an IaC (Infrastructure as Code) approach towards automating an Arc

Sep 18, 2022