all: Document the Output Formats feature

This commit also adds a new command, docshelper, with some utility funcs that adds a JSON datafiles to /docs/data that would be a pain to create and maintain by hand.

Fixes #3242

2 files changed, 100 insertions, 2 deletions

diff --git a/output/docshelper.go b/output/docshelper.go
new file mode 100644
index 000000000..e6b0ed28f
--- /dev/null
+++ b/output/docshelper.go
@@ -0,0 +1,86 @@
+package output
+
+import (
+	"strings"
+
+	"fmt"
+
+	"github.com/spf13/hugo/docshelper"
+)
+
+// This is is just some helpers used to create some JSON used in the Hugo docs.
+func init() {
+	docsProvider := func() map[string]interface{} {
+		docs := make(map[string]interface{})
+
+		docs["formats"] = DefaultFormats
+		docs["layouts"] = createLayoutExamples()
+		return docs
+	}
+
+	docshelper.AddDocProvider("output", docsProvider)
+}
+
+func createLayoutExamples() interface{} {
+
+	type Example struct {
+		Example      string
+		OutputFormat string
+		Suffix       string
+		Layouts      []string `json:"Template Lookup Order"`
+	}
+
+	var (
+		basicExamples []Example
+		demoLayout    = "demolayout"
+		demoType      = "demotype"
+	)
+
+	for _, example := range []struct {
+		name           string
+		d              LayoutDescriptor
+		hasTheme       bool
+		layoutOverride string
+		f              Format
+	}{
+		{`AMP home, with theme "demoTheme".`, LayoutDescriptor{Kind: "home"}, true, "", AMPFormat},
+		{"JSON home, no theme.", LayoutDescriptor{Kind: "home"}, false, "", JSONFormat},
+		{fmt.Sprintf(`CSV regular, "layout: %s" in front matter.`, demoLayout), LayoutDescriptor{Kind: "page", Layout: demoLayout}, false, "", CSVFormat},
+		{fmt.Sprintf(`JSON regular, "type: %s" in front matter.`, demoType), LayoutDescriptor{Kind: "page", Type: demoType}, false, "", CSVFormat},
+		{"HTML regular.", LayoutDescriptor{Kind: "page"}, false, "", HTMLFormat},
+		{"AMP regular.", LayoutDescriptor{Kind: "page"}, false, "", AMPFormat},
+		{"Calendar blog section.", LayoutDescriptor{Kind: "section", Section: "blog"}, false, "", CalendarFormat},
+		{"Calendar taxonomy list.", LayoutDescriptor{Kind: "taxonomy", Section: "tag"}, false, "", CalendarFormat},
+		{"Calendar taxonomy term.", LayoutDescriptor{Kind: "taxonomyTerm", Section: "tag"}, false, "", CalendarFormat},
+	} {
+
+		l := NewLayoutHandler(example.hasTheme)
+		layouts, _ := l.For(example.d, example.layoutOverride, example.f)
+
+		basicExamples = append(basicExamples, Example{
+			Example:      example.name,
+			OutputFormat: example.f.Name,
+			Suffix:       example.f.MediaType.Suffix,
+			Layouts:      makeLayoutsPresentable(layouts)})
+	}
+
+	return basicExamples
+
+}
+
+func makeLayoutsPresentable(l []string) []string {
+	var filtered []string
+	for _, ll := range l {
+		ll = strings.TrimPrefix(ll, "_text/")
+		if strings.Contains(ll, "theme/") {
+			ll = strings.Replace(ll, "theme/", "demoTheme/layouts/", -1)
+		} else {
+			ll = "layouts/" + ll
+		}
+		if !strings.Contains(ll, "indexes") {
+			filtered = append(filtered, ll)
+		}
+	}
+
+	return filtered
+}
diff --git a/output/outputFormat.go b/output/outputFormat.go
index ed3426411..bd0236278 100644
--- a/output/outputFormat.go
+++ b/output/outputFormat.go
@@ -14,6 +14,7 @@
 package output
 
 import (
+	"encoding/json"
 	"fmt"
 	"sort"
 	"strings"
@@ -299,6 +300,17 @@ func decode(mediaTypes media.Types, input, output interface{}) error {
 	return decoder.Decode(input)
 }
 
-func (t Format) BaseFilename() string {
-	return t.BaseName + "." + t.MediaType.Suffix
+func (f Format) BaseFilename() string {
+	return f.BaseName + "." + f.MediaType.Suffix
+}
+
+func (f Format) MarshalJSON() ([]byte, error) {
+	type Alias Format
+	return json.Marshal(&struct {
+		MediaType string
+		Alias
+	}{
+		MediaType: f.MediaType.String(),
+		Alias:     (Alias)(f),
+	})
 }