doc: add schema and template annotations (#657)

And add gotemplate to highlight.js as a custom language

doc/md/code-gen.md

@@ -111,8 +111,7 @@ as follows:
 entc generate --template <dir-path> --template glob="path/to/*.tmpl" ./ent/schema
 ```
 
-Example of a custom template provides a `Node` API for GraphQL - 
-[Github](https://github.com/facebookincubator/ent/blob/master/entc/integration/template/ent/template/node.tmpl).
+More information and examples can be found in the [external templates doc](templates.md).
 
 ## Use `entc` As A Package
 

doc/md/schema-edges.md

@@ -904,3 +904,31 @@ Indexes can be defined on multi fields and some types of edges as well.
 However, you should note, that this is currently an SQL-only feature.
 
 Read more about this in the [Indexes](schema-indexes.md) section.
+
+## Annotations
+
+`Annotations` is used to attach arbitrary metadata to the edge object in code generation.
+Template extensions can retrieve this metadata and use it inside their templates.
+
+Note that the metadata object must be serializable to a JSON raw value (e.g. struct, map or slice).
+
+```go
+// Pet schema.
+type Pet struct {
+	ent.Schema
+}
+
+// Edges of the Pet.
+func (Pet) Edges() []ent.Edge {
+	return []ent.Field{
+		edge.To("owner", User.Type).
+			Ref("pets").
+			Unique().
+			Annotations(entgql.Annotation{
+				OrderField: "OWNER",
+			}),
+	}
+}
+```
+
+Read more about annotations and their usage in templates in the [template doc](templates.md#annotations).

doc/md/schema-fields.md

@@ -496,3 +496,29 @@ func (User) Fields() []ent.Field {
 	}
 }
 ```
+
+## Annotations
+
+`Annotations` is used to attach arbitrary metadata to the field object in code generation.
+Template extensions can retrieve this metadata and use it inside their templates.
+
+Note that the metadata object must be serializable to a JSON raw value (e.g. struct, map or slice).
+
+```go
+// User schema.
+type User struct {
+	ent.Schema
+}
+
+// Fields of the user.
+func (User) Fields() []ent.Field {
+	return []ent.Field{
+		field.Time("creation_date").
+			Annotations(entgql.Annotation{
+				OrderField: "CREATED_AT",
+			}),
+	}
+}
+```
+
+Read more about annotations and their usage in templates in the [template doc](templates.md#annotations).

doc/md/templates.md

@@ -41,6 +41,62 @@ In order to override an existing template, use its name. For example:
 {{ end }}
 ```
 
+## Annotations
+Schema annotations allow to attach metadata to fields and edges and inject them to external templates.  
+An annotation must be a Go type that is serializable to JSON raw value (e.g. struct, map or slice)
+and implement the [Annotation](https://godoc.org/github.com/facebookincubator/ent/schema/field#Annotation) interface.
+
+Here's an example of an annotation and its usage in schema and template:
+
+1\. An annotation definition:
+```go
+package entgql
+
+// Annotation annotates fields with metadata for templates.
+type Annotation struct {
+	// OrderField is the ordering field as defined in graphql schema.
+	OrderField string
+}
+
+// Name implements ent.Annotation interface.
+func (Annotation) Name() string {
+	return "EntGQL"
+}
+```
+
+2\. Annotation usage in ent/schema:
+
+```go
+// User schema.
+type User struct {
+	ent.Schema
+}
+
+// Fields of the user.
+func (User) Fields() []ent.Field {
+	return []ent.Field{
+		field.Time("creation_date").
+			Annotations(entgql.Annotation{
+				OrderField: "CREATED_AT",
+			}),
+	}
+}
+```
+
+3\. Annotation usage in external template:
+```gotemplate
+{{ range $node := $.Nodes }}
+	{{ range $f := $node.Fields }}
+		{{/* Get the annotation by its name. See: Annotation.Name */}}
+		{{ if $annotation := $f.Annotations.EntGQL }}
+			{{/* Get the field from the annotation. */}}
+			{{ $orderField := $annotation.OrderField }}
+		{{ end }}
+	{{ end }}
+{{ end }}
+```
+
+
 ## Examples
 A custom template for implementing the `Node` API for GraphQL - 
 [Github](https://github.com/facebookincubator/ent/blob/master/entc/integration/template/ent/template/node.tmpl).

doc/website/siteConfig.js

@@ -75,6 +75,41 @@ const siteConfig = {
   highlight: {
     // Highlight.js theme to use for syntax highlighting in code blocks.
     theme: 'androidstudio',
+    hljs: function(hljs) {
+      hljs.registerLanguage('gotemplate', function(hljs) {
+          var GO_KEYWORDS = {
+              keyword:
+                  'break default func interface select case map struct chan else goto package switch ' +
+                  'const fallthrough if range type continue for import return var go defer ' +
+                  'bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 ' +
+                  'uint16 uint32 uint64 int uint uintptr rune with define block end',
+              literal:
+                  'true false iota nil',
+              built_in: 'append cap close complex copy imag len make new panic print println real recover delete' +
+                  'printf fail slice dict list'
+          };
+          return {
+              name: 'GoTemplate',
+              aliases: ['gotmpl'],
+              keywords: GO_KEYWORDS,
+              contains: [
+                  hljs.COMMENT('{{-* */\\*', '\\*/ *-*}}'),
+                  hljs.C_LINE_COMMENT_MODE,
+                  {
+                      className: 'string',
+                      variants: [
+                          hljs.QUOTE_STRING_MODE,
+                          hljs.APOS_STRING_MODE,
+                          {begin: '`', end: '`'},
+                      ]
+                  },
+                  {
+                      begin: /:=/
+                  },
+              ]
+          };
+      });
+    }
   },
 
   // Add custom scripts here that would be placed in <script> tags.