Add logic and examples for generic markdown and HTML drivers

cato.go

@@ -14,10 +14,10 @@ import (
 	"regexp"
 	"strings"
 
+	"github.com/cs3org/cato/exporter"
+	_ "github.com/cs3org/cato/exporter/drivers/loader"
+	"github.com/cs3org/cato/exporter/drivers/registry"
 	"github.com/cs3org/cato/resources"
-	"github.com/cs3org/cato/writer"
-	_ "github.com/cs3org/cato/writer/drivers/loader"
-	"github.com/cs3org/cato/writer/drivers/registry"
 )
 
 type structInfo struct {
@@ -195,17 +195,17 @@ func getConfigsToDocument(filePath, catoTag string) (map[string][]*resources.Fie
 	return configs, nil
 }
 
-func getDriver(c *resources.CatoConfig) (writer.ConfigWriter, error) {
+func getDriver(c *resources.CatoConfig) (exporter.ConfigExporter, error) {
 	if f, ok := registry.NewFuncs[c.Driver]; ok {
 		return f(c.DriverConfig[c.Driver])
 	}
 	return nil, fmt.Errorf("driver not found: %s", c.Driver)
 }
 
-func GenerateDocumentation(rootPath string, conf *resources.CatoConfig) error {
+func GenerateDocumentation(rootPath string, conf *resources.CatoConfig) (map[string]map[string][]*resources.FieldInfo, error) {
 
 	if rootPath == "" {
-		return fmt.Errorf("cato: root path can't be empty")
+		return nil, fmt.Errorf("cato: root path can't be empty")
 	}
 
 	if conf.CustomTag == "" {
@@ -214,27 +214,30 @@ func GenerateDocumentation(rootPath string, conf *resources.CatoConfig) error {
 
 	fileList, err := listGoFiles(rootPath)
 	if err != nil {
-		return fmt.Errorf("cato: error listing root path: %w", err)
+		return nil, fmt.Errorf("cato: error listing root path: %w", err)
 	}
 
-	writerDriver, err := getDriver(conf)
+	exporterDriver, err := getDriver(conf)
+	exportConfigs := true
 	if err != nil {
-		return fmt.Errorf("cato: error getting driver: %w", err)
+		// We don't export configs in this case
+		exportConfigs = false
 	}
 
+	filesConfigs := map[string]map[string][]*resources.FieldInfo{}
 	for _, file := range fileList {
-
 		configs, err := getConfigsToDocument(file, conf.CustomTag)
 		if err != nil {
-			return fmt.Errorf("cato: error parsing go file: %w", err)
+			return nil, fmt.Errorf("cato: error parsing go file: %w", err)
 		}
 
-		if len(configs) > 0 {
-			err = writerDriver.WriteConfigs(configs, file, rootPath)
+		if exportConfigs && len(configs) > 0 {
+			err = exporterDriver.ExportConfigs(configs, file, rootPath)
 			if err != nil {
-				return fmt.Errorf("cato: error writing documentation: %w", err)
+				return nil, fmt.Errorf("cato: error writing documentation: %w", err)
 			}
+			filesConfigs[file] = configs
 		}
 	}
-	return nil
+	return filesConfigs, nil
 }

cato_html_test.go

@@ -0,0 +1,19 @@
+package cato
+
+import (
+	"testing"
+
+	"github.com/cs3org/cato/resources"
+)
+
+func TestHTML(t *testing.T) {
+
+	rootPath := "examples/"
+	conf := &resources.CatoConfig{
+		Driver: "html",
+	}
+
+	if _, err := GenerateDocumentation(rootPath, conf); err != nil {
+		t.Errorf("GenerateDocumentation(): %w", err)
+	}
+}

cato_markdown_test.go

@@ -0,0 +1,24 @@
+package cato
+
+import (
+	"testing"
+
+	"github.com/cs3org/cato/resources"
+)
+
+func TestMarkdown(t *testing.T) {
+
+	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 := GenerateDocumentation(rootPath, conf); err != nil {
+		t.Errorf("GenerateDocumentation(): %w", err)
+	}
+}

examples/filesystem.go

@@ -0,0 +1,51 @@
+package main
+
+import "fmt"
+
+type FileSystem struct {
+	CacheDirectory     string   `docs:"/var/tmp/;Path of cache directory"`
+	EnableLogging      bool     `docs:"false;Whether to enable logging"`
+	AvailableChecksums []string `docs:"[adler, rabin];The list of checksums provided by the file system"`
+	// Configs for various metadata drivers
+	DriverConfig map[string]map[string]interface{} `docs:"{json:{encoding: UTF8}, xml:{encoding: ASCII}}"`
+	// Config for the HTTP uploads service
+	Uploads *UploadConfig `docs:"&UploadConfig{HTTPPrefix: uploads, DisableTus: false}"`
+}
+
+type UploadConfig struct {
+	// Whether to disable TUS protocol for uploads.
+	DisableTus bool `json:"disable_tus" docs:"false"`
+	// The prefix at which the uploads service should be exposed.
+	HTTPPrefix string `json:"http_prefix" docs:"uploads"`
+}
+
+func (fs FileSystem) init() {
+	if fs.CacheDirectory == "" {
+		fs.CacheDirectory = "/var/tmp/"
+	}
+	if len(fs.AvailableChecksums) == 0 {
+		fs.AvailableChecksums = []string{"adler", "rabin"}
+	}
+	if fs.DriverConfig == nil {
+		fs.DriverConfig = map[string]map[string]interface{}{
+			"json": map[string]interface{}{
+				"encoding": "UTF8",
+			},
+			"xml": map[string]interface{}{
+				"encoding": "ASCII",
+			},
+		}
+	}
+	if fs.Uploads == nil {
+		fs.Uploads = &UploadConfig{
+			HTTPPrefix: "uploads",
+		}
+	}
+}
+
+func main() {
+	fs := FileSystem{
+		AvailableChecksums: []string{"adler32"},
+	}
+	fmt.Printf("FileSystem: %+v", fs)
+}

examples/index.html

@@ -0,0 +1,43 @@
+
+<h2>struct: FileSystem</h2>
+<ul>
+  <li><b>CacheDirectory</b> - string</li>
+  <ul>
+    <li>Path of cache directory </li>
+    <li>Default: "/var/tmp/"</li>
+  </ul>
+  <li><b>EnableLogging</b> - bool</li>
+  <ul>
+    <li>Whether to enable logging </li>
+    <li>Default: false</li>
+  </ul>
+  <li><b>AvailableChecksums</b> - []string</li>
+  <ul>
+    <li>The list of checksums provided by the file system </li>
+    <li>Default: [adler, rabin]</li>
+  </ul>
+  <li><b>DriverConfig</b> - map[string]map[string]interface{}</li>
+  <ul>
+    <li>Configs for various metadata drivers </li>
+    <li>Default: {json:{encoding: UTF8}, xml:{encoding: ASCII}}</li>
+  </ul>
+  <li><b>Uploads</b> - *UploadConfig</li>
+  <ul>
+    <li>Config for the HTTP uploads service </li>
+    <li>Default: &UploadConfig{HTTPPrefix: uploads, DisableTus: false}</li>
+  </ul>
+</ul>
+
+<h2>struct: UploadConfig</h2>
+<ul>
+  <li><b>disable_tus</b> - bool</li>
+  <ul>
+    <li>Whether to disable TUS protocol for uploads. </li>
+    <li>Default: false</li>
+  </ul>
+  <li><b>http_prefix</b> - string</li>
+  <ul>
+    <li>The prefix at which the uploads service should be exposed. </li>
+    <li>Default: "uploads"</li>
+  </ul>
+</ul>

examples/index.md

@@ -0,0 +1,25 @@
+
+## struct: FileSystem
+- **CacheDirectory** - string
+  - Path of cache directory [[Ref]](https://github.com/cs3org/cato/tree/master/examples/filesystem.go#L6)
+  - Default: "/var/tmp/"
+- **EnableLogging** - bool
+  - Whether to enable logging [[Ref]](https://github.com/cs3org/cato/tree/master/examples/filesystem.go#L7)
+  - Default: false
+- **AvailableChecksums** - []string
+  - The list of checksums provided by the file system [[Ref]](https://github.com/cs3org/cato/tree/master/examples/filesystem.go#L8)
+  - Default: [adler, rabin]
+- **DriverConfig** - map[string]map[string]interface{}
+  - Configs for various metadata drivers [[Ref]](https://github.com/cs3org/cato/tree/master/examples/filesystem.go#L10)
+  - Default: {json:{encoding: UTF8}, xml:{encoding: ASCII}}
+- **Uploads** - *UploadConfig
+  - Config for the HTTP uploads service [[Ref]](https://github.com/cs3org/cato/tree/master/examples/filesystem.go#L12)
+  - Default: &UploadConfig{HTTPPrefix: uploads, DisableTus: false}
+
+## struct: UploadConfig
+- **disable_tus** - bool
+  - Whether to disable TUS protocol for uploads. [[Ref]](https://github.com/cs3org/cato/tree/master/examples/filesystem.go#L17)
+  - Default: false
+- **http_prefix** - string
+  - The prefix at which the uploads service should be exposed. [[Ref]](https://github.com/cs3org/cato/tree/master/examples/filesystem.go#L19)
+  - Default: "uploads"