README
¶
Gockel
If you squint really hard, you could call Gockel a GraphQL Schema documentation generator. But it doesn't really do anything. You have to do all the work.
Gockel was purpose-built for docs.sourcehut.org and may or may not generalize well to other use-cases. The templates for that site can be found here, so you can get an idea of how to use Gockel.
In a nutshell, Gockel loads a GraphQL schema from file (no introspection support), parses it into a gqlparser Schema, and - with some minor enhancements - throws that at a standard Go template, which you have to supply yourself.
That's right, there is no default theme. You have to write templates to make Gockel do anything at all.
Gockel does supply some useful helper functions to use in templates. These include support for rendering Markdown in comments and syntax highlighting GraphQL snippets (to render examples).
Usage
Usage of ./gockel:
-schema string
path to GraphQL Schema definition (default "schema.graphqls")
-templates string
path to template definitions (default "theme")
Extensibility
Additional helper functions can easily be added by writing a custom executable
wrapper. Just copy cmd/gockel/main.go and add a call to
Funcs() on the result of gockel.LoadTemplates() (called
root in main.go).
Contributing
Gockel is Free Software (MIT license). Feel free to send questions, patches, or other feedback to my public inbox.
Documentation
¶
Overview ¶
Package gockel provides some glue for loading a GraphQL schema definition from file, parse it as ast.Schema, and throw it at a template.Template. It does provide some enhancements for templating, see for example EnhancedSchema or helpers.
The main purpose of this package is to be used by git.sr.ht/~bitfehler/gockel/cmd/gockel, but for certain customizations it might be desirable to use it directly as library.
Index ¶
- func AddTemplateHelpers(root *template.Template)
- func LoadTemplates(path string) (*template.Template, error)
- type EnhancedSchema
- func (schema *EnhancedSchema) SortedMutations() ast.FieldList
- func (schema *EnhancedSchema) SortedQueries() ast.FieldList
- func (schema *EnhancedSchema) SortedSubscriptions() ast.FieldList
- func (schema *EnhancedSchema) SortedTypeDefinitions() ast.DefinitionList
- func (schema *EnhancedSchema) TypeDefinition(t *ast.Type) *string
- type Gckl
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddTemplateHelpers ¶
AddTemplateHelpers adds all functions from the package helpers to the provided root template's function map. In addition, a function "render" is added, which calls a template but returns the result as string for further processing (as opposed to rendering it to the output).
func LoadTemplates ¶
LoadTemplates recursively loads all files at path as templates.
It uses a built-in template as root that calls a template "main.html", so unless the resulting template is called with Gckl.ExecuteTemplate the provided path must contain a file called "main.html" which acts as root template.
Types ¶
type EnhancedSchema ¶
EnhancedSchema is a wrapper around ast.Schema with some convenience functions that are useful for templates.
func (*EnhancedSchema) SortedMutations ¶
func (schema *EnhancedSchema) SortedMutations() ast.FieldList
SortedMutations returns the schema's defined mutations, but alphabetically sorted and without internal types.
func (*EnhancedSchema) SortedQueries ¶
func (schema *EnhancedSchema) SortedQueries() ast.FieldList
SortedQueries returns the schema's defined queries, but alphabetically sorted and without internal types.
func (*EnhancedSchema) SortedSubscriptions ¶
func (schema *EnhancedSchema) SortedSubscriptions() ast.FieldList
SortedSubscriptions returns the schema's defined subscriptions, but alphabetically sorted and without internal types.
func (*EnhancedSchema) SortedTypeDefinitions ¶
func (schema *EnhancedSchema) SortedTypeDefinitions() ast.DefinitionList
SortedTypeDefinitions returns the schema's type definition, but alphabetically sorted, and excluding queries, mutations, and subscriptions.
func (*EnhancedSchema) TypeDefinition ¶
func (schema *EnhancedSchema) TypeDefinition(t *ast.Type) *string
TypeDefinition returns a the ID assigned to type definition for the type t. Returns nil for internal types or if the type is not defined in this schema.
type Gckl ¶
type Gckl struct {
// contains filtered or unexported fields
}
func Init ¶
Init initializes a new Gockel instance to render the GraphQL schema at filename using the provided template context root.
func (*Gckl) Execute ¶
Execute runs the rendering process, writing the output to w.
The template is applied to an EnhancedSchema instance. See also template.Template.Execute.
func (*Gckl) ExecuteTemplate ¶
ExecuteTemplate runs the rendering process, using the template name as root template, and writing the output to w.
The template is applied to an EnhancedSchema instance. See also template.Template.ExecuteTemplate.
Source Files
Directories