Fix issues with Sphinx docs and add docs test

Author: Cito

.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
 ^^^^^^^^^^