More fixes for ReST rendering in docstrings (#87)

Author: hoefling

docs/usage/extension.rst

@@ -17,7 +17,7 @@ follows::
         """))
 
 Note that this function expects the extensions as an AST, which we can get using the
-:func:`graphql.language.parse` function. Also note that the `extend_schema` function
+:func:`graphql.language.parse` function. Also note that the :func:`~graphql.extend_schema` function
 does not alter the original schema, but returns a new schema object.
 
 We also need to attach a resolver function to the new field::

src/graphql/execution/execute.py

@@ -97,8 +97,8 @@
 class ExecutionResult(NamedTuple):
     """The result of GraphQL execution.
 
-    - `data` is the result of a successful execution of the query.
-    - `errors` is included when any errors occurred as a non-empty list.
+    - ``data`` is the result of a successful execution of the query.
+    - ``errors`` is included when any errors occurred as a non-empty list.
     """
 
     data: Optional[Dict[str, Any]]
@@ -678,7 +678,8 @@ def complete_value(
         inner type on each item in the list.
 
         If the field type is a Scalar or Enum, ensures the completed value is a legal
-        value of the type by calling the `serialize` method of GraphQL type definition.
+        value of the type by calling the ``serialize`` method of GraphQL type
+        definition.
 
         If the field is an abstract type, determine the runtime type of the value and
         then complete based on that type.
@@ -948,7 +949,7 @@ def collect_subfields(
         """Collect subfields.
 
         A cached collection of relevant subfields with regard to the return type is
-        kept in the execution context as `_subfields_cache`. This ensures the
+        kept in the execution context as ``_subfields_cache``. This ensures the
         subfields are not repeatedly calculated, which saves overhead when resolving
         lists of values.
         """
@@ -1065,9 +1066,9 @@ def get_field_def(
     """Get field definition.
 
     This method looks up the field on the given type definition. It has special casing
-    for the two introspection fields, `__schema` and `__typename`. `__typename` is
+    for the two introspection fields, ``__schema`` and ``__typename``. ``__typename`` is
     special because it can always be queried as a field, even in situations where no
-    other fields are allowed, like on a Union. `__schema` could get automatically
+    other fields are allowed, like on a Union. ``__schema`` could get automatically
     added to the query type, but that would require mutating type definitions, which
     would cause issues.
 
@@ -1098,7 +1099,7 @@ def invalid_return_type_error(
 
 
 def get_typename(value: Any) -> Optional[str]:
-    """Get the `__typename` property of the given value."""
+    """Get the ``__typename`` property of the given value."""
     if isinstance(value, dict):
         return value.get("__typename")
     # need to de-mangle the attribute assumed to be "private" in Python
@@ -1117,11 +1118,12 @@ def default_type_resolver(
     If a resolve_type function is not given, then a default resolve behavior is used
     which attempts two strategies:
 
-    First, See if the provided value has a `__typename` field defined, if so, use that
+    First, See if the provided value has a ``__typename`` field defined, if so, use that
     value as name of the resolved type.
 
-    Otherwise, test each possible type for the abstract type by calling `is_type_of`
-    for the object being coerced, returning the first type that matches.
+    Otherwise, test each possible type for the abstract type by calling
+    :meth:`~graphql.type.GraphQLObjectType.is_type_of` for the object
+    being coerced, returning the first type that matches.
     """
     # First, look for `__typename`.
     type_name = get_typename(value)

src/graphql/execution/middleware.py

@@ -13,7 +13,7 @@ class MiddlewareManager:
 
     This class helps to wrap resolver functions with the provided middleware functions
     and/or objects. The functions take the next middleware function as first argument.
-    If middleware is provided as an object, it must provide a method `resolve` that is
+    If middleware is provided as an object, it must provide a method ``resolve`` that is
     used as the middleware function.
 
     Note that since resolvers return "AwaitableOrValue"s, all middleware functions

src/graphql/graphql.py

@@ -65,7 +65,8 @@ async def graphql(
     :arg type_resolver:
       A type resolver function to use when none is provided by the schema.
       If not provided, the default type resolver is used (which looks for a
-      `__typename` field or alternatively calls the `is_type_of` method).
+      ``__typename`` field or alternatively calls the
+      :meth:`~graphql.type.GraphQLObjectType.is_type_of` method).
     :arg middleware:
       The middleware to wrap the resolvers with
     :arg execution_context_class:

src/graphql/language/parser.py

@@ -77,14 +77,16 @@ def parse(
     Throws GraphQLError if a syntax error is encountered.
 
     By default, the parser creates AST nodes that know the location in the source that
-    they correspond to. The `no_location` option disables that behavior for performance
-    or testing.
+    they correspond to. The ``no_location`` option disables that behavior for
+    performance or testing.
 
     Experimental features:
 
-    If `experimental_fragment_variables` is set to True, the parser will understand
-    and parse variable definitions contained in a fragment definition. They'll be
-    represented in the `variable_definitions` field of the `FragmentDefinitionNode`.
+    If ``experimental_fragment_variables`` is set to ``True``, the parser will
+    understand and parse variable definitions contained in a fragment definition.
+    They'll be represented in the
+    :attr:`~graphql.language.FragmentDefinitionNode.variable_definitions` field
+    of the :class:`~graphql.language.FragmentDefinitionNode`.
 
     The syntax is identical to normal, query-defined variables. For example::
 
@@ -110,7 +112,8 @@ def parse_value(
     This is useful within tools that operate upon GraphQL Values directly and in
     isolation of complete GraphQL documents.
 
-    Consider providing the results to the utility function: `value_from_ast()`.
+    Consider providing the results to the utility function:
+    :func:`~graphql.value_from_ast`.
     """
     parser = Parser(
         source,
@@ -133,7 +136,8 @@ def parse_type(
     This is useful within tools that operate upon GraphQL Types directly and
     in isolation of complete GraphQL documents.
 
-    Consider providing the results to the utility function: `type_from_ast()`.
+    Consider providing the results to the utility function:
+    :func:`~graphql.value_from_ast`.
     """
     parser = Parser(
         source,
@@ -390,7 +394,7 @@ def parse_fragment_definition(self) -> FragmentDefinitionNode:
         )
 
     def parse_fragment_name(self) -> NameNode:
-        """FragmentName: Name but not `on`"""
+        """FragmentName: Name but not ``on``"""
         if self._lexer.token.value == "on":
             raise self.unexpected()
         return self.parse_name()
@@ -1042,9 +1046,10 @@ def any(
     ) -> List[T]:
         """Fetch any matching nodes, possibly none.
 
-        Returns a possibly empty list of parse nodes, determined by the `parse_fn`.
-        This list begins with a lex token of `open_kind` and ends with a lex token of
-        `close_kind`. Advances the parser to the next lex token after the closing token.
+        Returns a possibly empty list of parse nodes, determined by the ``parse_fn``.
+        This list begins with a lex token of ``open_kind`` and ends with a lex token of
+        ``close_kind``. Advances the parser to the next lex token after the closing
+        token.
         """
         self.expect_token(open_kind)
         nodes: List[T] = []
@@ -1058,10 +1063,11 @@ def optional_many(
     ) -> List[T]:
         """Fetch matching nodes, maybe none.
 
-        Returns a list of parse nodes, determined by the `parse_fn`. It can be empty
+        Returns a list of parse nodes, determined by the ``parse_fn``. It can be empty
         only if the open token is missing, otherwise it will always return a non-empty
-        list that begins with a lex token of `open_kind` and ends with a lex token of
-        `close_kind`. Advances the parser to the next lex token after the closing token.
+        list that begins with a lex token of ``open_kind`` and ends with a lex token of
+        ``close_kind``. Advances the parser to the next lex token after the closing
+        token.
         """
         if self.expect_optional_token(open_kind):
             nodes = [parse_fn()]
@@ -1076,9 +1082,10 @@ def many(
     ) -> List[T]:
         """Fetch matching nodes, at least one.
 
-        Returns a non-empty list of parse nodes, determined by the `parse_fn`.
-        This list begins with a lex token of `open_kind` and ends with a lex token of
-        `close_kind`. Advances the parser to the next lex token after the closing token.
+        Returns a non-empty list of parse nodes, determined by the ``parse_fn``.
+        This list begins with a lex token of ``open_kind`` and ends with a lex token of
+        ``close_kind``. Advances the parser to the next lex token after the closing
+        token.
         """
         self.expect_token(open_kind)
         nodes = [parse_fn()]

src/graphql/language/source.py

@@ -18,10 +18,10 @@ def __init__(
         """Initialize source input.
 
 
-        `name` and `location_offset` are optional. They are useful for clients who
+        ``name`` and ``location_offset`` are optional. They are useful for clients who
         store GraphQL documents in source files; for example, if the GraphQL input
         starts at line 40 in a file named Foo.graphql, it might be useful for name
-        to be "Foo.graphql" and location to be `(40, 0)`.
+        to be "Foo.graphql" and location to be ``(40, 0)``.
 
         line and column in location_offset are 1-indexed
         """

src/graphql/language/visitor.py

@@ -142,14 +142,14 @@ def enter(self, node, key, parent, path, ancestors):
     :arg parent: the parent immediately above this node, which may be an Array.
     :arg path: The key path to get to this node from the root node.
     :arg ancestors: All nodes and Arrays visited before reaching parent
-        of this node. These correspond to array indices in `path`.
+        of this node. These correspond to array indices in ``path``.
         Note: ancestors includes arrays which contain the parent of visited node.
 
     You can also define node kind specific methods by suffixing them with an underscore
-    followed by the kind of the node to be visited. For instance, to visit `field`
-    nodes, you would defined the methods `enter_field()` and/or `leave_field()`, with
-    the same signature as above. If no kind specific method has been defined for a given
-    node, the generic method is called.
+    followed by the kind of the node to be visited. For instance, to visit ``field``
+    nodes, you would defined the methods ``enter_field()`` and/or ``leave_field()``,
+    with the same signature as above. If no kind specific method has been defined
+    for a given node, the generic method is called.
     """
 
     # Provide special return values as attributes
@@ -200,18 +200,18 @@ class Stack(NamedTuple):
 def visit(root: Node, visitor: Visitor, visitor_keys=None) -> Any:
     """Visit each node in an AST.
 
-    `visit()` will walk through an AST using a depth first traversal, calling the
+    :func:`~.visit` will walk through an AST using a depth first traversal, calling the
     visitor's enter methods at each node in the traversal, and calling the leave methods
     after visiting that node and all of its child nodes.
 
     By returning different values from the enter and leave methods, the behavior of the
     visitor can be altered, including skipping over a sub-tree of the AST (by returning
     False), editing the AST by returning a value or None to remove the value, or to stop
-    the whole traversal by returning `BREAK`.
+    the whole traversal by returning :data:`~.BREAK`.
 
-    When using `visit()` to edit an AST, the original AST will not be modified, and a
-    new version of the AST with the changes applied will be returned from the visit
-    function.
+    When using :func:`~.visit` to edit an AST, the original AST will not be modified,
+    and a new version of the AST with the changes applied will be returned from the
+    visit function.
 
     To customize the node attributes to be used for traversal, you can provide a
     dictionary visitor_keys mapping node kinds to node attributes.

src/graphql/subscription/subscribe.py

@@ -51,7 +51,7 @@ async def subscribe(
 
     If the source stream could not be created due to faulty subscription resolver logic
     or underlying systems, the coroutine object will yield a single ExecutionResult
-    containing `errors` and no `data`.
+    containing ``errors`` and no ``data``.
 
     If the operation succeeded, the coroutine will yield an AsyncIterator, which yields
     a stream of ExecutionResults representing the response stream.
@@ -75,11 +75,11 @@ async def map_source_to_response(payload) -> ExecutionResult:
         """Map source to response.
 
         For each payload yielded from a subscription, map it over the normal GraphQL
-        `execute` function, with `payload` as the `root_value`. This implements the
-        "MapSourceToResponseEvent" algorithm described in the GraphQL specification.
-        The `execute` function provides the "ExecuteSubscriptionEvent" algorithm,
-        as it is nearly identical to the "ExecuteQuery" algorithm, for which `execute`
-        is also used.
+        :func:`~graphql.execute` function, with ``payload`` as the ``root_value``.
+        This implements the "MapSourceToResponseEvent" algorithm described in the
+        GraphQL specification. The :func:`~graphql.execute` function provides the
+        "ExecuteSubscriptionEvent" algorithm, as it is nearly identical to the
+        "ExecuteQuery" algorithm, for which :func:`~graphql.execute` is also used.
         """
         result = execute(
             schema,

src/graphql/type/definition.py

@@ -306,7 +306,7 @@ class GraphQLScalarType(GraphQLNamedType):
     and are defined with a name and a series of functions used to parse input from ast
     or variables and to ensure validity.
 
-    If a type's serialize function does not return a value (i.e. it returns `None`),
+    If a type's serialize function does not return a value (i.e. it returns ``None``),
     then no error will be included in the response.
 
     Example::
@@ -1245,7 +1245,7 @@ class GraphQLInputObjectType(GraphQLNamedType):
     An input object defines a structured collection of fields which may be supplied
     to a field argument.
 
-    Using `NonNull` will ensure that a value must be provided by the query.
+    Using ``NonNull`` will ensure that a value must be provided by the query.
 
     Example::
 
@@ -1261,7 +1261,7 @@ class GeoPoint(GraphQLInputObjectType):
             }
 
     The outbound values will be Python dictionaries by default, but you can have them
-    converted to other types by specifying an `out_type` function or class.
+    converted to other types by specifying an ``out_type`` function or class.
     """
 
     ast_node: Optional[InputObjectTypeDefinitionNode]

src/graphql/type/schema.py

@@ -78,8 +78,8 @@ class GraphQLSchema:
             # you want them to be included in the final schema.
             types=[human_type, droid_type])
 
-    Note: If a list of `directives` is provided to GraphQLSchema, that will be the
-    exact list of directives represented and allowed. If `directives` is not provided,
+    Note: If a list of ``directives`` is provided to GraphQLSchema, that will be the
+    exact list of directives represented and allowed. If ``directives`` is not provided,
     then a default set of the specified directives (e.g. @include and @skip) will be
     used. If you wish to provide *additional* directives to these specified directives,
     you must explicitly declare them. Example::
@@ -119,7 +119,7 @@ def __init__(
         """Initialize GraphQL schema.
 
         If this schema was built from a source known to be valid, then it may be marked
-        with `assume_valid` to avoid an additional type system validation.
+        with ``assume_valid`` to avoid an additional type system validation.
         """
         self._validation_errors = [] if assume_valid else None
 

src/graphql/utilities/build_ast_schema.py

@@ -36,9 +36,9 @@ def build_ast_schema(
     resolve methods, so execution will use default resolvers.
 
     When building a schema from a GraphQL service's introspection result, it might
-    be safe to assume the schema is valid. Set `assume_valid` to True to assume the
-    produced schema is valid. Set `assume_valid_sdl` to True to assume it is already
-    a valid SDL document.
+    be safe to assume the schema is valid. Set ``assume_valid`` to ``True`` to assume
+    the produced schema is valid. Set ``assume_valid_sdl`` to ``True`` to assume it is
+    already a valid SDL document.
     """
     if not isinstance(document_ast, DocumentNode):
         raise TypeError("Must provide valid Document AST.")

src/graphql/utilities/extend_schema.py

@@ -108,8 +108,9 @@ def extend_schema(
     copy. The original schema remains unaltered.
 
     When extending a schema with a known valid extension, it might be safe to assume the
-    schema is valid. Set `assume_valid` to true to assume the produced schema is valid.
-    Set `assume_valid_sdl` to True to assume it is already a valid SDL document.
+    schema is valid. Set ``assume_valid`` to ``True`` to assume the produced schema is
+    valid. Set ``assume_valid_sdl`` to ``True`` to assume it is already a valid SDL
+    document.
     """
     assert_schema(schema)
 

src/graphql/utilities/type_from_ast.py

@@ -44,7 +44,7 @@ def type_from_ast(schema, type_node):
 
     Given a Schema and an AST node describing a type, return a GraphQLType definition
     which applies to that type. For example, if provided the parsed AST node for
-    `[User]`, a GraphQLList instance will be returned, containing the type called
+    ``[User]``, a GraphQLList instance will be returned, containing the type called
     "User" found in the schema. If a type called "User" is not found in the schema,
     then None will be returned.
     """

src/graphql/utilities/type_info.py

@@ -56,7 +56,8 @@ class TypeInfo:
 
     TypeInfo is a utility class which, given a GraphQL schema, can keep track of the
     current field and type definitions at any point in a GraphQL document AST during
-    a recursive descent by calling `enter(node)` and `leave(node)`.
+    a recursive descent by calling :meth:`enter(node) <.TypeInfo.enter>` and
+    :meth:`leave(node) <.TypeInfo.leave>`.
     """
 
     def __init__(
@@ -262,9 +263,9 @@ def get_field_def(
 ) -> Optional[GraphQLField]:
     """Get field definition.
 
-    Not exactly the same as the executor's definition of `get_field_def()`, in this
-    statically evaluated environment we do not always have an Object type, and need
-    to handle Interface and Union types.
+    Not exactly the same as the executor's definition of
+    :func:`graphql.execution.get_field_def`, in this statically evaluated environment
+    we do not always have an Object type, and need to handle Interface and Union types.
     """
     name = field_node.name.value
     if name == "__schema" and schema.query_type is parent_type:

src/graphql/utilities/value_from_ast.py

@@ -33,7 +33,7 @@ def value_from_ast(
     A GraphQL type must be provided, which will be used to interpret different GraphQL
     Value literals.
 
-    Returns `Undefined` when the value could not be validly coerced according
+    Returns ``Undefined`` when the value could not be validly coerced according
     to the provided type.
 
     =================== ============== ================
@@ -143,7 +143,7 @@ def value_from_ast(
 def is_missing_variable(
     value_node: ValueNode, variables: Optional[Dict[str, Any]] = None
 ) -> bool:
-    """Check if `value_node` is a variable not defined in the `variables` dict."""
+    """Check if ``value_node`` is a variable not defined in the ``variables`` dict."""
     return isinstance(value_node, VariableNode) and (
         not variables or variables.get(value_node.name.value, Undefined) is Undefined
     )