Reorganize documentation to make room to grow (#84)
## Summary: In this commit I reorganize much of our documentation into a new `docs` directory, where there will hopefully be more room to grow and to organize things in a user-friendly way. There's almost no net-new documentation, although of course it's a great time to review it anyway. In particular: - I moved the documentation for the `genqlient.yaml` config file into an example file instead of GoDoc (which now just points to the example file); I think this will be a lot clearer for casual users. - I moved the documentation for the `@genqlient` directive out of GoDoc and into a GraphQL schema file (since while it's a comment it's all real syntax), likewise, and made the `GenqlientDirective` type private (since there's now nothing useful to do with it). - I moved `DESIGN.md` and the logo into `docs/` (just to keep the toplevel a bit cleaner), and separated the Contributing section of the README into `docs/CONTRIBUTING.md` (which github will automatically link on various issue and PR pages). This leaves it so that: - README.md is the only documentation at the toplevel (and will become just the high-level introduction as I add more user docs to `docs/`) - GoDoc is only documentation for if you want to call genqlient programmatically (which is fairly limited as the API surface is quite small: it's now just Main, Generate, and Config, plus a constructor, a single method, and a bunch of fields on the latter) In future commits, I'll add some more new documentation to the `docs` directory. Issue: https://github.com/Khan/genqlient/issues/26 ## Test plan: make check (and read the docs) Author: benjaminjkraft Reviewers: jvoll, benjaminjkraft, aberkan, dnerdy, MiguelCastillo, mahtabsabet Required Reviewers: Approved By: jvoll Checks: ✅ Lint, ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Lint Pull Request URL: https://github.com/Khan/genqlient/pull/84
This commit is contained in:
Ben Kraft
+14
-107
@@ -15,92 +15,21 @@ import (
|
||||
//
|
||||
// Callers must call ValidateAndFillDefaults before using the config.
|
||||
type Config struct {
|
||||
// The filename with the GraphQL schema (in SDL format); defaults to
|
||||
// schema.graphql
|
||||
Schema string `yaml:"schema"`
|
||||
|
||||
// Filenames or globs with the operations for which to generate code;
|
||||
// defaults to genqlient.graphql.
|
||||
//
|
||||
// These may be .graphql files, containing the queries in SDL format, or
|
||||
// Go files, in which case any string-literal starting with (optional
|
||||
// whitespace and) the string "# @genqlient" will be extracted as a query.
|
||||
Operations []string `yaml:"operations"`
|
||||
|
||||
// If set, a file at this path will be generated containing the exact
|
||||
// operations that genqlient will send to the server.
|
||||
//
|
||||
// This is useful for systems which require queries to be explicitly
|
||||
// safelisted, especially for cases like queries involving fragments where
|
||||
// it may not exactly match the input queries. The JSON is an object of
|
||||
// the form
|
||||
// {"operations": [{
|
||||
// "operationName": "operationname",
|
||||
// "query": "query operationName { ... }",
|
||||
// "sourceLocation": "myqueriesfile.graphql",
|
||||
// }]}
|
||||
// Keys may be added in the future.
|
||||
//
|
||||
// By default, no such file is written.
|
||||
ExportOperations string `yaml:"export_operations"`
|
||||
|
||||
// The filename to which to write the generated code; defaults to
|
||||
// generated.go
|
||||
Generated string `yaml:"generated"`
|
||||
|
||||
// The package name for the output code; defaults to the directory name of
|
||||
// Generated
|
||||
Package string `yaml:"package"`
|
||||
|
||||
// Set to the fully-qualified name of a Go type which generated helpers
|
||||
// should accept and use as the context.Context for HTTP requests.
|
||||
//
|
||||
// Defaults to context.Context; set to "-" to omit context entirely (i.e.
|
||||
// use context.Background()). Must be a type which implements
|
||||
// context.Context.
|
||||
ContextType string `yaml:"context_type"`
|
||||
|
||||
// If set, a function to get a graphql.Client, perhaps from the context.
|
||||
// By default, the client must be passed explicitly to each genqlient
|
||||
// generated query-helper.
|
||||
//
|
||||
// This is useful if you have a shared client, either a global, or
|
||||
// available from context, and don't want to pass it explicitly. In this
|
||||
// case the signature of the genqlient-generated helpers will omit the
|
||||
// `graphql.Context` and they will call this function instead.
|
||||
//
|
||||
// Must be the fully-qualified name of a function which accepts a context
|
||||
// (of the type configured as ContextType (above), which defaults to
|
||||
// `context.Context`, or a function of no arguments if ContextType is set
|
||||
// to the empty string) and returns (graphql.Client, error). If the
|
||||
// client-getter returns an error, the helper will return the error
|
||||
// without making a query.
|
||||
ClientGetter string `yaml:"client_getter"`
|
||||
|
||||
// A map from GraphQL type name to Go fully-qualified type name to override
|
||||
// the Go type genqlient will use for this GraphQL type.
|
||||
//
|
||||
// This is primarily used for custom scalars, or to map builtin scalars to
|
||||
// a nonstandard type. By default, builtin scalars are mapped to the
|
||||
// obvious Go types (String and ID to string, Int to int, Float to float64,
|
||||
// and Boolean to bool), but this setting will extend or override those
|
||||
// mappings.
|
||||
//
|
||||
// genqlient does not validate these types in any way; they must define
|
||||
// whatever logic is needed (MarshalJSON/UnmarshalJSON or JSON tags) to
|
||||
// convert to/from JSON. For this reason, it's not recommended to use this
|
||||
// setting to map object, interface, or union types, because nothing
|
||||
// guarantees that the fields requested in the query match those present in
|
||||
// the Go type.
|
||||
//
|
||||
// To get equivalent behavior in just one query, use @genqlient(bind: ...);
|
||||
// see GenqlientDirective.Bind for more details.
|
||||
Bindings map[string]*TypeBinding `yaml:"bindings"`
|
||||
// The following fields are documented at:
|
||||
// https://github.com/Khan/genqlient/blob/main/docs/genqlient.yaml
|
||||
Schema string `yaml:"schema"`
|
||||
Operations []string `yaml:"operations"`
|
||||
Generated string `yaml:"generated"`
|
||||
Package string `yaml:"package"`
|
||||
ExportOperations string `yaml:"export_operations"`
|
||||
ContextType string `yaml:"context_type"`
|
||||
ClientGetter string `yaml:"client_getter"`
|
||||
Bindings map[string]*TypeBinding `yaml:"bindings"`
|
||||
|
||||
// Set to true to use features that aren't fully ready to use.
|
||||
//
|
||||
// This is primarily intended for genqlient's own tests. These features
|
||||
// are likely BROKEN and come with NO EXPECTATION OF COMPATIBBILITY. Use
|
||||
// are likely BROKEN and come with NO EXPECTATION OF COMPATIBILITY. Use
|
||||
// them at your own risk!
|
||||
AllowBrokenFeatures bool `yaml:"allow_broken_features"`
|
||||
|
||||
@@ -110,32 +39,10 @@ type Config struct {
|
||||
}
|
||||
|
||||
// A TypeBinding represents a Go type to which genqlient will bind a particular
|
||||
// GraphQL type. See Config.Bind, above, for more details.
|
||||
// GraphQL type, and is documented further at:
|
||||
// https://github.com/Khan/genqlient/blob/main/docs/genqlient.yaml
|
||||
type TypeBinding struct {
|
||||
// The fully-qualified name of the Go type to which to bind. For example:
|
||||
// time.Time
|
||||
// map[string]interface{}
|
||||
// github.com/you/yourpkg/subpkg.MyType
|
||||
Type string `yaml:"type"`
|
||||
// If set, a GraphQL selection which must exactly match the fields
|
||||
// requested whenever this type is used. Only applies if the GraphQL type
|
||||
// is a composite output type (object, interface, or union).
|
||||
//
|
||||
// This is useful if Type is a struct whose UnmarshalJSON or other methods
|
||||
// expect that you requested certain fields. You can specify those fields
|
||||
// like
|
||||
// MyType:
|
||||
// type: path/to/my.GoType
|
||||
// expect_exact_fields: "{ id name }"
|
||||
// and then genqlient will reject if you make a query
|
||||
// { fieldOfMytype { id title } }
|
||||
// The fields must match exactly, including the ordering: "{ name id }"
|
||||
// will be rejected. But the arguments and directives, if any, need not
|
||||
// match.
|
||||
//
|
||||
// TODO(benkraft): Also add ExpectIncludesFields and ExpectSubsetOfFields,
|
||||
// or something, if you want to say, for example, that you have to request
|
||||
// certain fields but others are optional.
|
||||
Type string `yaml:"type"`
|
||||
ExpectExactFields string `yaml:"expect_exact_fields"`
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user