`graphqldomain`¶

This extension provides a Sphinx domain for describing GraphQL schemas.

In order to use this extension, add graphqldomain to the extensions list in your conf.py file.

extensions = ["graphqldomain"]

Directives¶

.. gql:directive:: definition¶

Describes a GraphQL directive defined in a schema.

The definition argument is the definition of the directive, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Type-System.Directives). However it should not include the following:

The Description, which goes into the body of this directive.
The directive keyword.

The :argument <name>: <description> field can be used to document the arguments (https://spec.graphql.org/June2018/#ArgumentsDefinition).

For example:

.. gql:directive:: @slow(super: Boolean = false) on FIELD_DEFINITION | ARGUMENT_DEFINITION

   Indicates that the usage of this field or argument is slow,
   and therefore queries with this field or argument should be made sparingly.

   :argument super: Whether usage will be super slow, or just a bit slow.

This will be rendered as:

directive @slow(super: Boolean = false) on FIELD_DEFINITION | ARGUMENT_DEFINITION¶

Indicates that the usage of this field or argument is slow, and therefore queries with this field or argument should be made sparingly.

Arguments:

super – Whether usage will be super slow, or just a bit slow.

.. gql:enum:: definition¶

Describes a GraphQL enum defined in a schema.

The definition argument is the definition of the enum, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Enums). However it should not include the following:

The Description, which goes into the body of this directive.
The enum keyword.
The EnumValuesDefinition. Enum values can be described with the gql:enum:value directive.

For example:

.. gql:enum:: CharacterCase

   The casing of a character.

This will be rendered as:

enum CharacterCase¶

The casing of a character.

.. gql:enum:value:: definition¶

Describes a GraphQL enum value defined on an enum in a schema.

The definition argument is the definition of the enum value, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#EnumValueDefinition). However it should not include the following:

The Description, which goes into the body of this directive.

For example:

.. gql:enum:: CharacterCase

   The casing of a character.

   .. gql:enum:value:: UPPER

      Upper case.

   .. gql:enum:value:: LOWER

      Lower case.

This will be rendered as:

enum CharacterCase¶

The casing of a character.

UPPER¶

Upper case.

LOWER¶

Lower case.

.. gql:input:: definition¶

Describes a GraphQL input object defined in a schema.

The definition argument is the definition of the input object, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Input-Objects). However it should not include the following:

The Description, which goes into the body of this directive.
The input keyword.
The InputFieldDefinition. Input values can be described with the gql:input:value directive.

For example:

.. gql:input:: Point2D

   A point in a 2D coordinate system.

This will be rendered as:

input Point2D¶: A point in a 2D coordinate system.

.. gql:input:field:: definition¶

Describes a GraphQL input field defined on an input in a schema.

The definition argument is the definition of the input field, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#InputValueDefinition). However it should not include the following:

The Description, which goes into the body of this directive.

For example:

.. gql:input:: Point2D

   A point in a 2D coordinate system.

   .. gql:input:field:: x: Float

      The ``x`` coordinate of the point.

   .. gql:input:field:: y: Float

      The ``y`` coordinate of the point.

This will be rendered as:

input Point2D¶

A point in a 2D coordinate system.

x: Float¶

The x coordinate of the point.

y: Float¶

The y coordinate of the point.

.. gql:interface:: definition¶

Describes a GraphQL interface defined on a schema.

The definition argument is the definition of the interface, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Interfaces). However it should not include the following:

The Description, which goes into the body of this directive.
The interface keyword.
The FieldsDefinition. Interface fields can be described with the gql:interface:field directive.

For example:

.. gql:interface:: NamedEntity

   An entity with a name.

This will be rendered as:

interface NamedEntity¶

An entity with a name.

.. gql:interface:field:: definition¶

Describes a GraphQL interface field defined on an interface in a schema.

The definition argument is the definition of the interface field, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#FieldDefinition). However it should not include the following:

The Description, which goes into the body of this directive.

The :argument <name>: <description> field can be used to document the arguments (https://spec.graphql.org/June2018/#ArgumentsDefinition).

For example:

.. gql:interface:: NamedEntity

   An entity with a name.

   .. gql:interface:field:: name(lower: Boolean = false): String

      The name of the entity.

      :argument lower: Whether to lowercase the name or not.

This will be rendered as:

interface NamedEntity¶

An entity with a name.

name(lower: Boolean = false): String¶

The name of the entity.

Arguments:

lower – Whether to lowercase the name or not.

.. gql:scalar:: definition¶

Describes a GraphQL scalar type defined on a schema.

The definition argument is the definition of the scalar type, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Scalars). However it should not include the following:

The Description, which goes into the body of this directive.
The scalar keyword.

For example:

.. gql:scalar:: Url

   A string that represents a valid URL.

This will be rendered as:

scalar Url¶

A string that represents a valid URL.

.. gql:schema:: definition¶

Describes a GraphQL schema.

The definition argument is the definition of the schema, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Schema). However it should not include the following:

The schema keyword.
The RootOperationTypeDefinition, which is documented via the optype field.

In other words, you should only include the directives (https://spec.graphql.org/June2018/#Directives).

The :optype <type> (query|mutation|subscription): field can be used to document the Root Operation Types (https://spec.graphql.org/June2018/#sec-Root-Operation-Types). If an optype field is specified without a type then it will default to the usual default Operation Types Query, Mutation, or Subscription.

Options

:name:¶: An arbitrary identifier given to the schema for use by Sphinx in cross-references and URLs to this schema. This can be useful for documenting multiple schemas in the same documentation, but isn’t necessary when documenting a single schema. Defaults to __gqlschema__.

For example:

.. gql:schema:: @mydirective
   :name: myschema

   An example schema.

   :optype MyQueryType query:
   :optype mutation:
   :optype MySubscriptionType subscription:

   .. gql:type:: MyQueryType

      Types and other definitions are usually grouped under a schema.

   .. gql:directive:: @mydirective on SCHEMA

This will be rendered as:

schema @mydirective¶

An example schema.

Operation types:

query: MyQueryType

mutation: Mutation

subscription: MySubscriptionType

type MyQueryType¶

Types and other definitions are usually grouped under a schema.

directive @mydirective on SCHEMA¶

.. gql:type:: definition¶

Describes a GraphQL object type defined on a schema.

The definition argument is the definition of the object type, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Objects). However it should not include the following:

The Description, which goes into the body of this directive.
The type keyword.
The FieldsDefinition. Interface fields can be described with the gql:type:field directive.

For example:

.. gql:type:: Person implements NamedEntity

   A human person.

This will be rendered as:

type Person implements NamedEntity ¶: A human person.

.. gql:type:field:: definition¶

Describes a GraphQL field defined on an object type in a schema.

The definition argument is the definition of the type field, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#FieldDefinition). However it should not include the following:

The Description, which goes into the body of this directive.
The type keyword.
The FieldsDefinition. Interface fields can be described with the gql:interface:value directive.

The :argument <name>: <description> field can be used to document the arguments (https://spec.graphql.org/June2018/#ArgumentsDefinition).

For example:

.. gql:type:: Person implements NamedEntity

   A human person.

   .. gql:type:field:: age: Int

      How old the person is in years.

   .. gql:type:field:: picture(format: String = "jpg"): Url

      :argument format: The desired file format of image.

This will be rendered as:

type Person implements NamedEntity ¶

A human person.

age: Int¶

How old the person is in years.

picture(format: String = "jpg"): Url ¶

Arguments:

format – The desired file format of image.

.. gql:union:: definition¶

Describes a GraphQL union defined on a schema.

The definition argument is the definition of the union, using the format described in the GraphQL spec (https://spec.graphql.org/June2018/#sec-Unions). However it should not include the following:

The Description, which goes into the body of this directive.
The union keyword.

For example:

.. gql:union:: Centre = Person | Point2D

   A possible centre of the universe.

This will be rendered as:

union Centre = Person | Point2D ¶

A possible centre of the universe.

Roles¶

All GraphQL directives have a role with the same name that can be used to refer to those objects. For example a GraphQL type defined with the gql:type directive can be referred to using the gql:type role.

:gql:directive:¶: Refers to a GraphQL directive defined with the gql:directive rST directive.

:gql:enum:¶: Refers to a GraphQL enum defined with the gql:enum rST directive.

:gql:enum:value:¶: Refers to a GraphQL enum value defined with the gql:enum:value rST directive.

:gql:input:¶: Refers to a GraphQL input defined with the gql:input rST directive.

:gql:input:field:¶: Refers to a GraphQL input field defined with the gql:input:field rST directive.

:gql:interface:¶: Refers to a GraphQL interface defined with the gql:interface rST directive.

:gql:interface:field:¶: Refers to a GraphQL interface field defined with the gql:interface:field rST directive.

:gql:scalar:¶: Refers to a GraphQL scalar defined with the gql:scalar rST directive.

:gql:schema:¶: Refers to a GraphQL schema defined with the gql:schema rST directive.

:gql:type:¶: Refers to a GraphQL type defined with the gql:type rST directive.

:gql:type:field:¶: Refers to a GraphQL type field defined with the gql:type:field rST directive.

:gql:union:¶: Refers to a GraphQL union defined with the gql:union rST directive.

Using Schema Names In Roles¶

If you are documenting a single schema and therefore choose not to use the :name: option to name your gql:schema, using the schema name in roles is never required.

For example:

.. gql:schema::

   .. gql:type:: MyType1

      This can link to :gql:type:`MyType2`
      or :gql:type:`__gqlschema__.MyType2`,
      but both are rendered the same.

   .. gql:type:: MyType2

This can link to :gql:type:`MyType2`
or :gql:type:`__gqlschema__.MyType2`,
but both are rendered the same.

This will be rendered as:

schema ¶

type MyType1¶

This can link to MyType2 or MyType2, but both are rendered the same.

type MyType2¶

This can link to MyType2 or MyType2, but both are rendered the same.

Advanced¶

If you have more complex documentation that uses the :name: option to name one or more gql:schema definitions, then using the schema name in roles is often required to eliminate a role ever having ambiguous targets (e.g. if two schemas defined a MyType type, a gql:type to MyType could link to the MyType type from either schema).

Roles used inside a schema definition can skip prepending the schema name. Roles used outside a schema must prepend the schema name for named schemas.

For example:

.. gql:schema::
   :name: roleschema1

   .. gql:type:: RoleType1

      This can link to :gql:type:`RoleType2`
      or :gql:type:`roleschema1.RoleType2`.

   .. gql:type:: RoleType2

This can link to :gql:type:`roleschema1.RoleType2`
but cannot link to :gql:type:`RoleType2`.

This will be rendered as:

schema ¶

type RoleType1¶

This can link to RoleType2 or roleschema1.RoleType2.

type RoleType2¶

This can link to roleschema1.RoleType2 but cannot link to RoleType2.

graphqldomain¶

Directives¶

Roles¶

Using Schema Names In Roles¶

Advanced¶

`graphqldomain`¶