Fix issues with Sphinx docs and add docs test

.travis.yml

@@ -2,7 +2,7 @@ language: python
 
 matrix:
   include:
-    - env: TOXENV=black,flake8,mypy
+    - env: TOXENV=black,flake8,mypy,docs
       python: 3.7
       dist: xenial
       sudo: true

docs/conf.py

@@ -115,7 +115,6 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/intro.rst

@@ -41,6 +41,8 @@ Now you can start using GraphQL-core-next by importing from the top-level
 :mod:`graphql` package. Nearly everything defined in the sub-packages
 can also be imported directly from the top-level package.
 
+.. currentmodule:: graphql
+
 For instance, using the types defined in the :mod:`graphql.type` package,
 you can define a GraphQL schema, like this simple one::
 

docs/modules/error.rst

@@ -1,6 +1,8 @@
 Error
 =====
 
+.. currentmodule:: graphql.error
+
 .. automodule:: graphql.error
 
 .. autoexception:: GraphQLError
@@ -10,6 +12,4 @@ Error
 .. autofunction:: print_error
 .. autofunction:: format_error
 
-The :mod:`graphql.error` module also contains the :const:`INVALID` singleton that is
-used to describe invalid or undefined values and corresponds to the ``undefined``
-value in GraphQL.js.
+.. autodata:: INVALID

docs/modules/execution.rst

@@ -1,6 +1,8 @@
 Execution
 =========
 
+.. currentmodule:: graphql.execution
+
 .. automodule:: graphql.execution
 
 .. autofunction:: execute

docs/modules/graphql.rst

@@ -1,6 +1,8 @@
 Reference
 =========
 
+.. currentmodule:: graphql
+
 .. automodule:: graphql
 
 .. _top-level-functions:

docs/modules/language.rst

@@ -99,5 +99,25 @@ Visitor
 .. autoclass:: ParallelVisitor
 .. autoclass:: TypeInfoVisitor
 
-The module also exports the constants :const:`BREAK`, :const:`SKIP`, :const:`REMOVE` and
-:const:`IDLE` that are used as special return values in the :class:`Visitor` methods.
+The module also exports the following special symbols which can be used as
+return values in the :class:`Visitor` methods to signal particular actions:
+
+.. data:: BREAK
+   :annotation: = True
+
+   This return value signals that no further nodes shall be visited.
+
+.. data:: SKIP
+   :annotation: = False
+
+   This return value signals that the current node shall be skipped.
+
+.. data:: REMOVE
+   :annotation: = Ellipsis
+
+   This return value signals that the current node shall be deleted.
+
+.. data:: IDLE
+   :annotation: = None
+
+   This return value signals that no additional action shall take place.

docs/modules/pyutils.rst

@@ -1,6 +1,8 @@
 PyUtils
 =======
 
+.. currentmodule:: graphql.pyutils
+
 .. automodule:: graphql.pyutils
 
 .. autofunction:: camel_to_snake
@@ -18,5 +20,6 @@ PyUtils
 .. autofunction:: or_list
 .. autofunction:: quoted_or_list
 .. autofunction:: suggestion_list
-.. autofunction:: ReadOnlyError
-.. autofunction:: ReadOnlyList
+.. autoclass:: ReadOnlyError
+.. autoclass:: ReadOnlyList
+.. autoclass:: ReadOnlyDict

docs/modules/subscription.rst

@@ -1,6 +1,8 @@
 Subscription
 ============
 
+.. currentmodule:: graphql.subscription
+
 .. automodule:: graphql.subscription
 
 .. autofunction:: subscribe

docs/modules/type.rst

@@ -1,8 +1,11 @@
 Type
 ====
 
+.. currentmodule:: graphql.type
+
 .. automodule:: graphql.type
 
+
 Definition
 ----------
 
@@ -99,6 +102,7 @@ Resolvers
 .. autoclass:: GraphQLTypeResolver
 .. autoclass:: ResponsePath
 
+
 Directives
 ----------
 
@@ -116,11 +120,13 @@ Definitions
 .. autoclass:: GraphQLSkipDirective
 .. autoclass:: GraphQLDeprecatedDirective
 
-The list of all specified directives is available as
-:data:`specified_directives`.
+.. autodata:: specified_directives
+
+.. data:: DEFAULT_DEPRECATION_REASON
+   :annotation: = 'No longer supported'
+
+   String constant that can be used as the default value for ``deprecation_reason``.
 
-The module also exports the constant :const:`DEFAULT_DEPRECATION_REASON`
-that can be used as the default value for :obj:`deprecation_reason`.
 
 Introspection
 -------------
@@ -130,7 +136,6 @@ Predicates
 
 .. autofunction:: is_introspection_type
 
-
 Definitions
 ^^^^^^^^^^^
 
@@ -139,8 +144,8 @@ Definitions
 .. autoclass:: TypeNameMetaFieldDef
 .. autoclass:: SchemaMetaFieldDef
 
-The list of all introspection types is available as
-:data:`introspection_types`.
+.. autodata:: introspection_types
+
 
 Scalars
 -------
@@ -162,6 +167,7 @@ Definitions
 The list of all specified directives is available as
 :data:`specified_directives`.
 
+
 Schema
 ------
 
@@ -184,7 +190,6 @@ Functions:
 
 .. autofunction:: validate_schema
 
-
 Assertions
 ^^^^^^^^^^
 

docs/modules/utilities.rst

@@ -1,6 +1,8 @@
 Utilities
 =========
 
+.. currentmodule:: graphql.utilities
+
 .. automodule:: graphql.utilities
 
 The GraphQL query recommended for a full schema introspection:

docs/modules/validation.rst

@@ -1,12 +1,25 @@
 Validation
 ==========
 
+.. currentmodule:: graphql.validation
+
 .. automodule:: graphql.validation
 
 .. autofunction:: validate
 
+.. autoclass:: ASTValidationContext
+
+.. autoclass:: ASTValidationRule
+
+.. autoclass:: SDLValidationContext
+
+.. autoclass:: SDLValidationRule
+
 .. autoclass:: ValidationContext
 
+.. autoclass:: ValidationRule
+
+
 Rules
 -----
 
@@ -15,6 +28,7 @@ rules in this list has been adjusted to lead to the most clear output when encou
 multiple validation errors:
 
 .. autodata:: specified_rules
+   :annotation: = ReadOnlyList([...])
 
 Spec Section: "Executable Definitions"
 
@@ -119,4 +133,3 @@ Spec Section: "Variables are Input Types"
 Spec Section: "All Variable Usages Are Allowed"
 
 .. autoclass:: VariablesInAllowedPositionRule
-

docs/usage/methods.rst

@@ -52,6 +52,6 @@ In a similar vein, you can also attach resolvers as methods to the resolved obje
 deeper levels than the root of the query. In that case, instead of resolving to
 dictionaries with keys for all the fields, as we did above, you would resolve to objects
 with attributes for all the fields. For instance, you would define a class ``Human``
-with a method :meth:`friends` for resolving the friends of a human. You can also make
+with a method ``friends()`` for resolving the friends of a human. You can also make
 use of inheritance in this case. The ``Human`` class and a ``Droid`` class could inherit
 from a ``Character`` class and use its methods as resolvers for common fields.

docs/usage/other.rst

@@ -1,10 +1,12 @@
 Subscriptions
 -------------
 
+.. currentmodule:: graphql.subscription
+
 Sometimes you need to not only query data from a server, but you also want to push data
 from the server to the client. GraphQL-core-next has you also covered here, because it
 implements the "Subscribe" algorithm described in the GraphQL spec. To execute a GraphQL
-subscription, you must use the :func:`graphql.subscribe` method from the
+subscription, you must use the :func:`subscribe` method from the
 :mod:`graphql.subscription` module. Instead of a single ``ExecutionResult``, this
 function returns an asynchronous iterator yielding a stream of those, unless there was
 an immediate error. Of course you will then also need to maintain a persistent channel

docs/usage/parser.rst

@@ -1,6 +1,8 @@
 Parsing GraphQL Queries and Schema Notation
 -------------------------------------------
 
+.. currentmodule:: graphql.language
+
 When executing GraphQL queries, the first step that happens under the hood is parsing
 the query. But GraphQL-core-next also exposes the parser for direct usage via the
 :func:`graphql.language.parse` function. When you pass this function a GraphQL source
@@ -58,12 +60,12 @@ This will give the same result as manually creating the AST document::
         ])
 
 
-When parsing with `no_location=False` (the default), the AST nodes will also have a
-:attr:`loc` attribute carrying the information on the source code location corresponding
+When parsing with ``no_location=False`` (the default), the AST nodes will also have a
+``loc`` attribute carrying the information on the source code location corresponding
 to the AST nodes.
 
 When there is a syntax error in the GraphQL source code, then the :func:`parse` function
-will raise a :exc:`GraphQLSyntaxError`.
+will raise a :exc:`graphql.error.GraphQLSyntaxError`.
 
 The parser can not only be used to parse GraphQL queries, but also to parse the GraphQL
 schema definition language. This will result in another way of representing a GraphQL

docs/usage/queries.rst

@@ -1,6 +1,8 @@
 Executing Queries
 -----------------
 
+.. currentmodule:: graphql.execution
+
 Now that we have defined the schema and breathed life into it with our resolver
 functions, we can execute arbitrary query against the schema.
 
@@ -36,8 +38,8 @@ should get the expected result::
         data={'droid': {'name': 'R2-D2', 'primaryFunction': 'Astromech'}},
         errors=None)
 
-The :class:`execution.ExecutionResult` has a :attr:`data` attribute with the actual
-result, and an :attr:`errors` attribute with a list of errors if there were any.
+The :class:`ExecutionResult` has a ``data`` attribute with the actual result, and an
+``errors`` attribute with a list of errors if there were any.
 
 If all your resolvers work synchronously, as in our case, you can also use the
 :func:`graphql.graphql_sync` function to query the result in ordinary synchronous code::
@@ -118,7 +120,7 @@ Finally, let's see what happens when we try to access the secret backstory of ou
 
 While we get the name of the hero, the secret backstory fields remains empty, since its
 resolver function raises an error. However, we get the error that has been raised by the
-resolver in the :attr:`errors` attribute of the result::
+resolver in the ``errors`` attribute of the result::
 
     ExecutionResult(
         data={'hero': {'name': 'Luke Skywalker', 'secretBackstory': None}},

docs/usage/resolvers.rst

@@ -81,10 +81,10 @@ Note that the resolver functions get the current object as first argument. For a
 on the root Query type this is often not used, but a root object can also be defined
 when executing the query. As the second argument, they get an object containing
 execution information, as defined in the :class:`graphql.type.GraphQLResolveInfo` class.
-This object also has a :attr:`context` attribute that can be used to provide every
-resolver with contextual information like the currently logged in user, or a database
-session. In our simple example we don't authenticate users and use static data instead
-of a database, so we don't make use of it here. In addition to these two arguments,
+This object also has a ``context`` attribute that can be used to provide every resolver
+with contextual information like the currently logged in user, or a database session.
+In our simple example we don't authenticate users and use static data instead of a
+database, so we don't make use of it here. In addition to these two arguments,
 resolver functions optionally get the defined for the field in the schema, using the
 same names (the names are not translated from GraphQL naming conventions to Python
 naming conventions).

docs/usage/schema.rst

@@ -1,6 +1,8 @@
 Building a Type Schema
 ----------------------
 
+.. currentmodule:: graphql.type
+
 Using the classes in the :mod:`graphql.type` sub-package as building blocks, you can
 build a complete GraphQL type schema.
 

docs/usage/validator.rst

@@ -1,6 +1,8 @@
 Validating GraphQL Queries
 --------------------------
 
+.. currentmodule:: graphql.validation
+
 When executing GraphQL queries, the second step that happens under the hood after
 parsing the source code is a validation against the given schema using the rules of the
 GraphQL specification. You can also run the validation step manually by calling the
@@ -33,8 +35,9 @@ In this case, we will get::
          " sub selection of subfields. Did you mean 'friends { ... }'?",
          locations=[SourceLocation(line=6, column=9)])]
 
-These rules are implemented in the :mod:`graphql.validation.rules` module. Instead of
-the default rules, you can also use a subset or create custom rules. The rules are based
-on the :class:`graphql.validation.ValidationRule` class which is based on the
+These rules are available in the :data:`specified_rules` list and implemented in the
+``graphql.validation.rules`` subpackage. Instead of the default rules,
+you can also use a subset or create custom rules. The rules are
+based on the :class:`graphql.validation.ValidationRule` class which is based on the
 :class:`graphql.language.Visitor` class which provides a way of walking through an AST
 document using the visitor pattern.

graphql/__init__.py

@@ -34,7 +34,7 @@
   - :mod:`graphql.error`: Creating and formatting GraphQL errors.
   - :mod:`graphql.utilities`:
      Common useful computations upon the GraphQL language and type objects.
-  - :mod:`graphql/subscription`: Subscribe to data updates.
+  - :mod:`graphql.subscription`: Subscribe to data updates.
 """
 
 __version__ = "1.0.4"

graphql/error/format_error.py

@@ -8,7 +8,7 @@
 
 
 def format_error(error: "GraphQLError") -> Dict[str, Any]:
-    """Format a GraphQL error
+    """Format a GraphQL error.
 
     Given a GraphQLError, format it according to the rules described by the "Response
     Format, Errors" section of the GraphQL Specification.

graphql/error/invalid.py

@@ -22,3 +22,9 @@ def __ne__(self, other):
 
 # Used to indicate invalid values (like "undefined" in GraphQL.js):
 INVALID = InvalidType()
+
+INVALID.__doc__ = """Symbol for invalid or undefined values
+
+This singleton object is used to describe invalid or undefined values.
+It corresponds to the ``undefined`` value in GraphQL.js.
+"""