Upgrade Sphinx and fix various autodoc issues (#104)

Author: Cito

docs/conf.py

@@ -85,50 +85,121 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # AutoDoc configuration
-#autoclass_content = "both"
+autoclass_content = "class"
 autodoc_default_options = {
     'members': True,
     'inherited-members': True,
-    'private-members': False,
     'special-members': '__init__',
     'undoc-members': True,
     'show-inheritance': True
 }
 autosummary_generate = True
 
-# ignore certain warnings
-# (references to some of the Python built-in types do not resolve correctly)
+# GraphQL-core top level modules with submodules that can be omitted.
+# Sometimes autodoc cannot find classes since it is looking for the
+# qualified form, but the documentation has the shorter form.
+# We need to give autodoc a little help in this cases.
+graphql_modules = {
+    'error': ['graphql_error'],
+    'execution': ['execute', 'middleware'],
+    'language': ['ast', 'directive_locations', 'location',
+                 'source', 'token_kind', 'visitor'],
+    'pyutils': ['event_emitter', 'frozen_list', 'path'],
+    'type': ['definition', 'directives', 'schema'],
+    'utilities': ['find_breaking_changes', 'type_info'],
+    'validation': ['rules', 'validation_context']}
+
+# GraphQL-core classes that autodoc sometimes cannot find
+# (e.g. where specified as string in type hints).
+# We need to give autodoc a little help in this cases, too:
+graphql_classes = {
+    'GraphQLAbstractType': 'type',
+    'GraphQLObjectType': 'type',
+    'Node': 'language',
+    'Source': 'language',
+    'SourceLocation': 'language'
+}
+
+# ignore the following undocumented or internal references:
+ignore_references = set('''
+GNT GT T
+enum.Enum
+asyncio.events.AbstractEventLoop
+graphql.type.schema.InterfaceImplementations
+graphql.validation.validation_context.VariableUsage
+graphql.validation.rules.known_argument_names.KnownArgumentNamesOnDirectivesRule
+graphql.validation.rules.provided_required_arguments.ProvidedRequiredArgumentsOnDirectivesRule
+'''.split())
+
+ignore_references.update(__builtins__.keys())
+
+
+def on_missing_reference(app, env, node, contnode):
+    """Fix or skip any missing references."""
+    if node.get('refdomain') != 'py':
+        return None
+    target = node.get('reftarget')
+    if not target:
+        return None
+    if target in ignore_references:
+        return contnode
+    typ = node.get('reftype')
+    if typ != 'class':
+        return None
+    if '.' in target:  # maybe too specific
+        base_module, target = target.split('.', 1)
+        if base_module == 'typing':
+            return contnode
+        if base_module == 'graphql':
+            if '.' not in target:
+                return None
+            base_module, target = target.split('.', 1)
+        if '.' not in target:
+            return None
+        sub_modules = graphql_modules.get(base_module)
+        if not sub_modules:
+            return
+        sub_module = target.split('.', 1)[0]
+        if sub_module not in sub_modules:
+            return None
+        target = 'graphql.' + base_module + '.' + target.rsplit('.', 1)[-1]
+    else:  # maybe not specific enough
+        base_module = graphql_classes.get(target)
+        if not base_module:
+            return None
+        target = 'graphql.' + base_module + '.' + target
+    # replace target
+    if contnode.__class__.__name__ == 'Text':
+        contnode = contnode.__class__(target)
+    elif contnode.__class__.__name__ == 'literal':
+        if len(contnode.children) != 1:
+            return None
+        textnode = contnode.children[0]
+        contnode.children[0] = textnode.__class__(target)
+    else:
+        return None
+    node['reftarget'] = target
+    fromdoc = node.get('refdoc')
+    if not fromdoc:
+        doc_module = node.get('py:module')
+        if doc_module:
+            if doc_module.startswith('graphql.'):
+                doc_module = doc_module.split('.', 1)[-1]
+            if doc_module not in graphql_modules:
+                doc_module = None
+        fromdoc = 'modules/' + (doc_module or base_module)
+    # try resolving again with replaced target
+    return env.domains['py'].resolve_xref(
+        env, fromdoc, app.builder, typ, target, node, contnode)
+
+
+def setup(app):
+    app.connect('missing-reference', on_missing_reference)
+
+
+# be nitpicky (handle all possible problems in on_missing_reference)
 nitpicky = True
-nitpick_ignore = [('py:class', t) for t in (
-    'dict', 'list', 'object', 'tuple',
-    'Exception', 'TypeError', 'ValueError',
-    'builtins.str', 'enum.Enum',
-    'typing.Callable', 'typing.Dict', 'typing.Generic', 'typing.List',
-    'graphql.pyutils.cached_property.CachedProperty',
-    'graphql.pyutils.path.Path',
-    'graphql.error.graphql_error.GraphQLError',
-    'graphql.language.ast.DefinitionNode',
-    'graphql.language.ast.ExecutableDefinitionNode',
-    'graphql.language.ast.Node',
-    'graphql.language.ast.ScalarTypeDefinitionNode',
-    'graphql.language.ast.SelectionNode',
-    'graphql.language.ast.TypeDefinitionNode',
-    'graphql.language.ast.TypeExtensionNode',
-    'graphql.language.ast.TypeNode',
-    'graphql.language.ast.TypeSystemDefinitionNode',
-    'graphql.language.ast.ValueNode',
-    'graphql.language.visitor.Visitor',
-    'graphql.type.definition.GraphQLNamedType',
-    'graphql.type.definition.GraphQLType',
-    'graphql.type.definition.GraphQLWrappingType',
-    'graphql.validation.rules.ASTValidationRule',
-    'graphql.validation.rules.SDLValidationRule',
-    'graphql.validation.rules.ValidationRule',
-    'graphql.validation.validation_context.ASTValidationContext',
-    'graphql.validation.rules.known_argument_names'
-    '.KnownArgumentNamesOnDirectivesRule',
-    'graphql.validation.rules.provided_required_arguments'
-    '.ProvidedRequiredArgumentsOnDirectivesRule')]
+
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -172,7 +243,9 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'navigation_depth': 5
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/diffs.rst

@@ -49,6 +49,8 @@ The following shorthand notations are possible:
 * Where you need to pass a GraphQLEnumValueMap, i.e. a dictionary with names as keys and GraphQLEnumValues as values, you can pass any other Python objects as values. These will be automatically wrapped into GraphQLEnumValues. You can also pass a Python Enum type as GraphQLEnumValueMap.
 
 
+.. currentmodule:: graphql.type
+
 Custom output names of arguments and input fields
 -------------------------------------------------
 
@@ -61,18 +63,22 @@ Custom output types of input object types
 You can also pass a custom ``out_type`` argument to :class:`GraphQLInputObjectType` that allows conversion to any Python type on egress instead of conversion to a dictionary, which is the default. This is used to support the container feature of Graphene InputObjectTypes.
 
 
+.. currentmodule:: graphql.execution
+
 Custom middleware
 -----------------
 
-The :func:`execution.execute` function takes an additional ``middleware`` argument which must be a sequence of middleware functions or a :class:`MiddlewareManager` object. This feature is used by Graphene to affect the evaluation of fields using custom middleware. There has been a `request <https://github.com/graphql/graphql-js/issues/1516>`_ to add this to GraphQL.js as well, but so far this feature only exists in GraphQL-core.
+The :func:`execute` function takes an additional ``middleware`` argument which must be a sequence of middleware functions or a :class:`MiddlewareManager` object. This feature is used by Graphene to affect the evaluation of fields using custom middleware. There has been a `request <https://github.com/graphql/graphql-js/issues/1516>`_ to add this to GraphQL.js as well, but so far this feature only exists in GraphQL-core.
 
 
 Custom execution context
 ------------------------
 
-The :func:`execution.execute` function takes an additional ``execution_context_class`` argument which allows specifying a custom execution context class instead of the default :class:`ExecutionContext` used by GraphQL-core.
+The :func:`execute` function takes an additional ``execution_context_class`` argument which allows specifying a custom execution context class instead of the default :class:`ExecutionContext` used by GraphQL-core.
 
 
+.. currentmodule:: graphql
+
 Registering special types for descriptions
 ------------------------------------------
 

docs/modules/error.rst

@@ -4,12 +4,3 @@ Error
 .. currentmodule:: graphql.error
 
 .. automodule:: graphql.error
-
-.. autoexception:: GraphQLError
-   :members:
-
-.. autoexception:: GraphQLSyntaxError
-
-.. autofunction:: format_error
-.. autofunction:: located_error
-.. autofunction:: print_error

docs/modules/execution.rst

@@ -4,12 +4,3 @@ Execution
 .. currentmodule:: graphql.execution
 
 .. automodule:: graphql.execution
-
-.. autofunction:: execute
-.. autofunction:: default_field_resolver
-
-.. autoclass:: ExecutionContext
-.. autoclass:: ExecutionResult
-
-.. autofunction:: get_directive_values
-

docs/modules/graphql.rst

@@ -4,6 +4,8 @@ Reference
 .. currentmodule:: graphql
 
 .. automodule:: graphql
+   :no-members:
+   :no-inherited-members:
 
 .. _top-level-functions:
 
@@ -19,7 +21,7 @@ Sub-Packages
 ------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    error
    execution

docs/modules/language.rst

@@ -1,7 +1,11 @@
 Language
 ========
 
+.. currentmodule:: graphql.language
+
 .. automodule:: graphql.language
+   :no-members:
+   :no-inherited-members:
 
 AST
 ---
@@ -65,6 +69,10 @@ Each kind of AST node has its own class:
 .. autoclass:: VariableDefinitionNode
 .. autoclass:: VariableNode
 
+Directive locations are specified using the following enumeration:
+
+.. autoclass:: DirectiveLocation
+
 Lexer
 -----
 
@@ -99,8 +107,17 @@ Visitor
 .. autoclass:: Visitor
 .. autoclass:: ParallelVisitor
 
-The module also exports the following special symbols which can be used as
-return values in the :class:`Visitor` methods to signal particular actions:
+The module also exports the following enumeration that can be used as the return type
+for :class:`Visitor` methods:
+
+.. currentmodule:: graphql.language.visitor
+
+.. autoclass:: VisitorActionEnum
+
+.. currentmodule:: graphql.language
+
+The module also exports the values of this enumeration directly. These can be used as
+return values of :class:`Visitor` methods to signal particular actions:
 
 .. data:: BREAK
    :annotation: (same as ``True``)

docs/modules/pyutils.rst

@@ -4,6 +4,8 @@ PyUtils
 .. currentmodule:: graphql.pyutils
 
 .. automodule:: graphql.pyutils
+   :no-members:
+   :no-inherited-members:
 
 .. autofunction:: camel_to_snake
 .. autofunction:: snake_to_camel
@@ -12,21 +14,26 @@ PyUtils
 .. autofunction:: register_description
 .. autofunction:: unregister_description
 .. autoclass:: EventEmitter
-   :members:
 .. autoclass:: EventEmitterAsyncIterator
-   :members:
 .. autofunction:: identity_func
 .. autofunction:: inspect
 .. autofunction:: is_finite
 .. autofunction:: is_integer
 .. autoclass:: AwaitableOrValue
-   :members:
 .. autofunction:: suggestion_list
 .. autoclass:: FrozenError
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
 .. autoclass:: FrozenList
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
 .. autoclass:: FrozenDict
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
 .. autoclass:: Path
-   :members:
 .. autofunction:: print_path_list
 
 .. autodata:: Undefined

docs/modules/subscription.rst

@@ -5,6 +5,3 @@ Subscription
 
 .. automodule:: graphql.subscription
 
-.. autofunction:: subscribe
-.. autofunction:: create_source_event_stream
-

docs/modules/type.rst

@@ -4,7 +4,8 @@ Type
 .. currentmodule:: graphql.type
 
 .. automodule:: graphql.type
-
+   :no-members:
+   :no-inherited-members:
 
 Definition
 ----------

docs/modules/utilities.rst

@@ -4,6 +4,8 @@ Utilities
 .. currentmodule:: graphql.utilities
 
 .. automodule:: graphql.utilities
+   :no-members:
+   :no-inherited-members:
 
 The GraphQL query recommended for a full schema introspection: